⚙️ Configuration & Developer Experience

[vasconceloscezar]

Summary

Improve configuration management and developer experience. Enable per-repository configs that can be shared with team members and better tooling validation.

Problems Identified

1. Per-Repository Scripts Configuration

Current: Scripts (setup, dev server, cleanup) configured in UI, stored locally.
Impact: Other team members can't reuse configs, manual setup on each machine.

Solution:

• Store project config in .genie/forge.json or similar
• Committed to repo, version controlled
• UI reads/writes to this file
• Fallback to local config if file missing

Proposed Schema:

{
  "scripts": {
    "setup": "make setup-dev",
    "dev": "make dev",
    "cleanup": "make quality"
  },
  "copyFiles": [".env", ".env.local"],
  "defaultBranch": "dev",
  "agents": {
    "preferred": "claude-code"
  }
}

2. Cursor CLI Validation

Current: Selecting Cursor as provider doesn't validate CLI installation.
Impact: Cryptic errors later when trying to execute tasks.

Solution:

• Check CLI availability when provider selected
• Show version if found: "Cursor CLI v1.2.3 ✓"
• Show install instructions if missing
• Optional: block save until CLI available (or show warning)

3. Provider Tool Validation (General)

Current: No validation that required tools are installed.

Solution:

• Validation for each provider's requirements
• Clear error messages with install instructions
• "Test Connection" button for providers
• Health check on app startup

4. Better Error Messages

Current: Some errors are cryptic, especially for missing dependencies.

Solution:

• Human-readable error messages
• Suggested fixes for common errors
• Links to documentation
• Copy-able error details for bug reports

5. Team Config Sharing

Current: Each user configures independently.

Solution:

• .genie/forge.json shared in repo
• Override mechanism for personal settings
• Environment variable support in configs
• Secrets handled separately (not committed)

Acceptance Criteria

• Project config can be stored in .genie/forge.json
• Cursor CLI validated on provider selection
• Clear error messages with suggested fixes
• Team members can share project configs via git

Technical Notes

File Structure:

project/
├── .genie/
│   ├── forge.json      # Project config (committed)
│   └── forge.local.json # Personal overrides (gitignored)

Implementation:

• Config loader with merge logic (repo + local)
• Provider validation hooks
• Error message registry with suggestions

Team Feedback Sources

• Feedback 1: Cursor CLI validation
• Feedback 6: Per-repo scripts, team config

Priority

🟢 P2 - Medium (DX improvement, enables team workflows)