Feature Request: Sync verified features back to app_spec.txt

Problem

The app_spec.txt file has an <implemented_features> section that is populated ONLY during initial spec generation. When features move through the Kanban board lifecycle:

Backlog → In Progress → Waiting Approval → Verified → Completed

The app_spec.txt is NEVER updated. It remains a static snapshot from the initial project setup.

Current Behavior

1. User creates project with app_spec.txt
2. AI generates features, some marked as "implemented" based on code analysis
3. User implements NEW features via Kanban board
4. Features move to "Verified" then "Completed"
5. app_spec.txt <implemented_features> section remains UNCHANGED
6. Disconnect between spec and reality grows over time

Real example from seo-optimization project:

• Feature claude-ai-integration has status: "completed" in feature.json
• But app_spec.txt <implemented_features> section doesn't reflect this completion
• The spec shows what was detected at generation time, not current state

Why This Matters

1. app_spec.txt becomes stale - Unreliable as source of truth
2. AI generating new features doesn't know current state - May suggest already-implemented features
3. Project documentation is inaccurate - Spec doesn't match reality
4. Onboarding friction - New team members see outdated spec
5. Regeneration loses progress - If user regenerates spec, completed features aren't preserved

Expected Behavior

When a feature reaches verified or completed status, it should be:

1. Added to <implemented_features> section in app_spec.txt
2. Formatted consistently with existing entries
3. Persisted so spec reflects actual project state

Suggested Implementation

Option A: Auto-sync on verification (Recommended)

Automatically update app_spec.txt when feature status changes to verified/completed:

// In apps/server/src/services/feature-loader.ts or auto-mode-service.ts

async function updateFeatureStatus(projectPath: string, featureId: string, newStatus: string) {
  // ... existing status update logic ...

  if (newStatus === 'verified' || newStatus === 'completed') {
    await syncFeatureToAppSpec(projectPath, feature);
  }
}

async function syncFeatureToAppSpec(projectPath: string, feature: Feature) {
  const specPath = path.join(projectPath, '.automaker', 'app_spec.txt');
  const specContent = await fs.readFile(specPath, 'utf-8');

  // Parse XML, find <implemented_features> section
  // Add new <feature> entry if not already present
  // Write back with proper XML formatting

  const featureEntry = `      <feature>${escapeXml(feature.title)}: ${escapeXml(feature.description.slice(0, 100))}</feature>`;

  // Insert before </implemented_features> closing tag
  const updatedSpec = specContent.replace(
    '</implemented_features>',
    `${featureEntry}\n    </implemented_features>`
  );

  await fs.writeFile(specPath, updatedSpec);
}

Option B: Manual sync button

Add a "Sync to Spec" button in the Kanban board header:

// In board-view.tsx toolbar
<Button onClick={handleSyncToSpec} variant="outline">
  <RefreshCw className="w-4 h-4 mr-2" />
  Sync to Spec
</Button>

This would:

1. Collect all verified/completed features
2. Show diff preview of changes to app_spec.txt
3. Allow user to confirm before saving

Option C: Periodic reconciliation

Add a "Reconcile Spec" action in Spec view:

1. Compare features directory with app_spec.txt
2. Show discrepancies in a modal
3. Allow selective sync of completed features

Files to Modify

Code References

Feature status update (no spec sync):

• apps/server/src/services/auto-mode-service.ts:967-993

Feature persistence:

• apps/server/src/services/feature-loader.ts:update()

App spec format utilities:

• apps/server/src/lib/app-spec-format.ts

XML Format Considerations

The <implemented_features> section uses this format:

<implemented_features>
  <feature_group name="Group Name">
    <feature>Feature description here</feature>
    <feature>Another feature description</feature>
  </feature_group>
</implemented_features>

Options for adding new features:

1. Add to existing group - Match category to feature_group name
2. Create new group - "Kanban Completed" or use feature category
3. Flat list - Add without grouping at the end

Edge Cases to Consider

Acceptance Criteria

• When feature status changes to "verified", app_spec.txt is updated
• When feature status changes to "completed", app_spec.txt is updated
• New features appear in <implemented_features> section
• XML formatting is preserved (proper escaping, indentation)
• Duplicate entries are prevented
• Sync is atomic (no partial updates on failure)
• Error handling doesn't break feature status updates

Future Enhancements

1. Bi-directional sync - Changes to app_spec.txt reflected in Kanban
2. Conflict resolution - Handle manual spec edits
3. Version history - Track spec changes over time
4. Spec regeneration awareness - Preserve completed features on regenerate

Labels

enhancement, feature-management, spec-management, data-integrity