Bug: ACP gets confused when I make a workspace for a repo that has existing specs

[jwm4]

🐛 Bug Description

Summary: This repo has some existing specs that were created using Claude Code and spec-kit:

• https://github.com/jwm4/lendyr-red

When I try to make a new workspace using this repo, it sees that I already have a specs/001-lendyr-red-banking and a similar 002 directory.

Expected Behavior: I expected it to start a new spec beginning with 003 since I already have 001 and 002 specs.

Actual Behavior: It went directly to a done state because the 001-... folder was already there.

✅ Acceptance Criteria

• Bug is reproduced and root cause identified
• Fix is implemented and tested
• Regression tests added to prevent future occurrences
• Documentation updated if needed
• Fix is verified in staging environment

🏷️ Labels

• Priority: [low/medium/high/critical]
• Complexity: [trivial/easy/medium/hard]
• Component: [frontend/backend/operator/tools/docs]

[bobbravo2]

@claude triage and find the root cause of this bug. Plan a fix and regression testing plan to hand off to another agent.

[claude]

Claude finished @bobbravo2's task —— View job

---

Bug Triage: ACP Workspace Confusion with Existing Specs ✅

Task: Investigate root cause and plan fix for workspace creation bug with existing specs

Completed Analysis

• ✅ Searched codebase for workspace creation logic
• ✅ Searched for spec numbering/detection code
• ✅ Identified root cause of the bug
• ✅ Documented root cause analysis
• ✅ Planned fix approach
• ✅ Designed regression testing strategy
• ✅ Provided handoff summary

---

Root Cause Analysis

The Bug: When creating a new workspace for a repo that already has existing specs (001, 002, etc.), ACP goes directly to "done" state instead of creating a new spec (003).

Root Cause Identified:

The issue is in how vTeam checks if a repository is "seeded". The seeding check (CheckRepoSeeding in components/backend/git/operations.go:158-203) looks for:

1. .claude/commands/ directory
2. .claude/agents/ directory
3. .specify/ directory

The problem: This check is done at the repository level (checking if these directories exist on the branch), NOT at the workspace/spec level. When a repo already has 001-* and 002-* specs from previous work, these directories already exist at the repo root, so the system thinks it's "done seeding" and shows the workspace as ready.

Current Flow:

1. User creates RFE with repo https://github.com/jwm4/lendyr-red (which already has specs/001-lendyr-red-banking/)
2. System calls CheckRepoSeeding() on the feature branch
3. Finds .claude/commands/, .claude/agents/, .specify/ exist (from previous work)
4. Returns isSeeded = true
5. UI shows workspace as ready, but specs/{branchName}/ doesn't exist yet!

Expected Flow:

1. User creates RFE with repo that has existing specs
2. System should check if specs/{branchName}/ exists specifically
3. If not, mark as not seeded and trigger seeding to create that directory
4. Create numbered spec directory (or use branch-named directory)

---

Fix Plan

Option 1: Check for Spec Directory Existence (Recommended)

Modify CheckRepoSeeding() to also verify that specs/{branchName}/ exists on the target branch:

File: components/backend/git/operations.go

Changes needed:

// CheckRepoSeeding checks if a repo has been seeded by verifying .claude/commands/ and .specify/ exist
// AND that the specific workspace directory exists for this feature
func CheckRepoSeeding(ctx context.Context, repoURL string, branch *string, githubToken string) (bool, map[string]interface{}, error) {
    owner, repo, err := ParseGitHubURL(repoURL)
    if err != nil {
        return false, nil, err
    }

    branchName := "main"
    if branch != nil && strings.TrimSpace(*branch) != "" {
        branchName = strings.TrimSpace(*branch)
    }

    // ... existing checks for .claude/commands, .claude/agents, .specify ...

    // NEW: Check if specs/{branchName}/ directory exists
    specsPathExists, err := checkGitHubPathExists(ctx, owner, repo, branchName, fmt.Sprintf("specs/%s", branchName), githubToken)
    if err != nil {
        return false, nil, fmt.Errorf("failed to check specs/%s: %w", branchName, err)
    }

    details := map[string]interface{}{
        "claudeExists":         claudeExists,
        "claudeCommandsExists": claudeCommandsExists,
        "claudeAgentsExists":   claudeAgentsExists,
        "specifyExists":        specifyExists,
        "specsPathExists":      specsPathExists,  // NEW
    }

    // Repo is properly seeded if all critical components exist AND the workspace directory exists
    isSeeded := claudeCommandsExists && claudeAgentsExists && specifyExists && specsPathExists
    return isSeeded, details, nil
}

Pros:

• Minimal change, focused fix
• Correctly identifies when a workspace needs setup
• Works with existing architecture

Cons:

• Doesn't address the numbered spec pattern (001-, 002-, etc.)

Option 2: Support Numbered Spec Directories

If vTeam should support the numbered spec pattern (like spec-kit's 001-feature, 002-feature), we'd need more extensive changes:

1. Add logic to scan existing specs/ directory and find highest number
2. Auto-increment to create next numbered directory
3. Update branch naming to follow {number}-{feature-name} pattern

This is a larger feature addition and may not be the intended behavior.

---

Recommended Fix: Option 1

Rationale:

• The current architecture uses specs/{branchName}/ where branchName is user-defined (e.g., ambient-feature-name)
• The seeding process already creates specs/{branchName}/ at line 597 of operations.go
• We just need to verify this directory exists before marking as seeded

---

Regression Testing Plan

Test Cases to Add

1. Fresh Repo Seeding (baseline - should still work)

• Create RFE with repo that has never been seeded
• Expected: Seeding required, creates .claude/, .specify/, and specs/{branchName}/
• Status: Should pass with fix

2. Repo with Existing Specs (the reported bug)

• Create RFE with repo that already has specs/001-feature/ and .claude/, .specify/ at root
• Use a new branch name (e.g., ambient-new-feature)
• Expected: Seeding required (because specs/ambient-new-feature/ doesn't exist)
• Status: Currently fails - marks as seeded immediately
• Status after fix: Should pass

3. Re-seeding Same Branch

• Create RFE with branch name that already has workspace
• Expected: Marked as seeded (idempotent)
• Status: Should pass with fix

4. Multiple Features in Progress

• Create RFE Outcome: Reduce Refinement Time with agent System #1 with branch ambient-feature-a, seed it
• Create RFE Epic: RAT Architecture & Design #2 with branch ambient-feature-b on same repo
• Expected: RFE Epic: RAT Architecture & Design #2 requires seeding (different workspace)
• Status: Should pass with fix

Integration Tests

File: components/backend/tests/integration/rfe_seeding_test.go (new file)

func TestCheckRepoSeeding_WithExistingSpecs(t *testing.T) {
    // Setup: Mock GitHub API to return:
    // - .claude/commands exists
    // - .claude/agents exists
    // - .specify exists
    // - specs/001-existing exists
    // - specs/ambient-new-feature does NOT exist
    
    isSeeded, details, err := git.CheckRepoSeeding(ctx, repoURL, &branchName, token)
    
    assert.NoError(t, err)
    assert.False(t, isSeeded, "Should not be seeded when workspace dir doesn't exist")
    assert.True(t, details["claudeCommandsExists"].(bool))
    assert.True(t, details["specifyExists"].(bool))
    assert.False(t, details["specsPathExists"].(bool))
}

Manual Testing Checklist

• Test with https://github.com/jwm4/lendyr-red (the actual reported repo)
• Verify seeding creates specs/{branchName}/ directory
• Verify workspace shows as "not seeded" initially
• Verify after seeding, workspace shows as "ready"
• Test with a fresh repo (no existing specs)
• Test with numbered spec repos (001-, 002- pattern)

---

Handoff Summary

For the Implementation Agent:

1. Primary Fix Location: components/backend/git/operations.go:158-203

   • Function: CheckRepoSeeding()
   • Add check for specs/{branchName}/ directory existence
   • Include in return details and seeding calculation

2. Testing Requirements:

   • Add integration test in components/backend/tests/integration/
   • Test against repo with existing specs
   • Verify idempotency

3. Files to Modify:

   • components/backend/git/operations.go (CheckRepoSeeding function)
   • components/backend/tests/integration/rfe_seeding_test.go (new file for tests)

4. Validation:

   • Manual test with https://github.com/jwm4/lendyr-red
   • Run existing integration tests to ensure no regression
   • Verify UI correctly shows "needs seeding" state

5. Edge Cases to Consider:

   • Branch name with special characters
   • Very long branch names
   • Branch names that conflict with existing directories

---

Status: Analysis complete. Ready for implementation by another agent.
| Branch: claude/issue-210-20251030-0119

[sallyom]

🔍 Bug Review & Assessment Complete

📄 View Full Analysis (detailed assessment and implementation plan)

Session: 210-bug-review-1762118289

---

Generated by vTeam BugFix Workspace

[sallyom]

🔧 Implementation Complete

📄 View Implementation Details (full summary and code changes)

📋 Next Steps

Create a Pull Request to merge these changes:

1. 🌿 View changes: bugfix/gh-210
2. 🔀 Click "Contribute" → "Open pull request" on GitHub
3. 📝 Review the changes and submit the PR

To review locally:

git fetch origin bugfix/gh-210
git checkout bugfix/gh-210

---

Session: 210-bug-implement-fix-1762119336
Generated by vTeam BugFix Workspace

[sallyom]

🔄 Jira Task Updated

Jira task RHOAILT-503 has been updated with the latest information.

📄 Latest Analysis

• Implementation Details

Synchronized by vTeam BugFix Workspace

[Gkrumbach07]

Tracked in Jira: https://issues.redhat.com/browse/RHOAIENG-39101