SpecifyPlus Monorepo Structure Conflict Report (Phase II Hackathon)

[Msaleemakhtar]

Date: 2025-12-04

1. Issue Description

During the transition to Phase II of the Hackathon, a significant conflict has arisen between the desired monorepo project structure outlined in the Hackathon II - Todo Spec-Driven Development.md document and the default behavior of the specifyplus bash scripts.

Specifically, the Hackathon document mandates a structured specs directory (e.g., specs/features/<short-name>.md for specifications and specs/features/<short-name>/ for associated planning and task artifacts), managed by a .spec-kit/config.yaml. In contrast, the specifyplus bash scripts, particularly create-new-feature.sh and the path derivation logic in common.sh, are rigidly coupled to a specs/<branch-name>/ directory structure (e.g., specs/001-task-crud-web/spec.md).

2. Impact

This discrepancy leads to several problems:

• Manual Intervention: To conform to the desired monorepo structure for Phase II, manual file movement and directory management are required after executing specifyplus commands that generate new files.
• Command Failures: Subsequent specifyplus commands (e.g., /sp.plan, /sp.tasks, /sp.clarify, /sp.implement) fail because common.sh attempts to locate or create artifact files in the specs/<branch-name>/ structure, which no longer contains the moved files, or tries to create them in the wrong place.
• Broken Automation: The core benefit of specifyplus—automating the SDD workflow—is significantly degraded, requiring the AI agent (and user) to perform repetitive manual corrections.
• Violation of Workflow Strictness: It prevents strict adherence to the documented workflow for generating specifications, plans, and tasks.

3. Root Cause Analysis

The root cause lies in the path resolution mechanism within the specifyplus bash scripts:

• common.sh::get_feature_paths: This critical function, utilized by almost all specifyplus commands, relies directly on get_current_branch (which provides the Git branch name, e.g., 001-task-crud-web) to construct all artifact paths. It hardcodes paths like FEATURE_DIR='specs/$current_branch', FEATURE_SPEC='$feature_dir/spec.md', etc.
• create-new-feature.sh: This script directly uses the output of get_feature_paths to create initial feature directories and spec files in the specs/<branch-name>/ structure.
• Ignored .spec-kit/config.yaml: The current specifyplus bash scripts do not read or utilize the .spec-kit/config.yaml file to dynamically determine desired feature/artifact locations.

4. Possible Solutions & Trade-offs

Solution 1: Manual Workarounds (Current Practice)

• Description: Continue to run specifyplus commands (e.g., create-new-feature.sh) for their side effects (like branch creation), but manually manage all file creation and movement to adhere to the desired monorepo structure. This involves manually moving spec.md files from specs/<branch-name>/spec.md to specs/features/<short-name>.md, manually creating directories like specs/features/<short-name>/ for plan/tasks, and populating them.
• Pros: No modification to specifyplus core scripts (adheres to original "DON'T modify scripts" constraint).
• Cons: Highly inefficient, error-prone, completely defeats the purpose of specifyplus automation, requires constant manual intervention for every SDD step of every feature. Not scalable beyond simple projects. This is what currently occurs.

Solution 2: Adapt Monorepo Structure to specifyplus (Compromise)

• Description: Modify the desired Phase II monorepo structure to align with specifyplus's default behavior. Instead of specs/features/task-crud.md, utilize the specs/<branch-name>/ structure directly (e.g., specs/001-task-crud-web/spec.md, specs/001-task-crud-web/plan.md). This would mean forgoing the specs/features/ subdirectory and the task-crud.md naming convention.
• Pros: No modifications to specifyplus scripts, allows specifyplus automation to function as designed.
• Cons: Does not fully achieve the desired structured monorepo layout from the Hackathon II document, potentially leads to a less organized specs directory if many features exist, and the .spec-kit/config.yaml remains unused for path resolution.

Solution 3: Comprehensive Refactoring of specifyplus Bash Scripts (Recommended)

• Description: Modify the core specifyplus bash scripts to dynamically interpret and use the monorepo structure defined in .spec-kit/config.yaml. This is a significant refactoring but would fully enable automation with the desired structure.
• Pros: Fully automated, achieves the desired monorepo structure from the Hackathon II document, scalable for future phases, aligns tool behavior with architectural vision.
• Cons: Requires explicit authorization to modify multiple specifyplus core scripts (relaxing the initial "DON'T modify scripts" constraint), significant development effort to implement and thoroughly test.
• Specific Modifications Needed:
  • common.sh:
    • Implement a function to read and parse .spec-kit/config.yaml.
    • Modify get_feature_paths to resolve FEATURE_DIR, FEATURE_SPEC, IMPL_PLAN, TASKS based on the configured features_dir (e.g., specs/features/) and a feature slug derived from the branch name or directly provided. Feature-specific plan/tasks would reside in a subdirectory (e.g., specs/features/<slug>/plan.md).
  • create-new-feature.sh:
    • Update file creation logic to use the new path derived from common.sh.
    • Create the spec file directly at specs/features/<slug>.md.
    • Create a corresponding subdirectory specs/features/<slug>/ for plan, tasks, etc.
  • setup-plan.sh: Update to ensure plan.md is created in the correct specs/features/<slug>/plan.md location.
  • create-phr.sh: Adjust routing logic to correctly place feature-specific PHRs into history/prompts/<slug>/.
  • check-prerequisites.sh: Ensure all prerequisite checks use the updated path derivation logic.

5. Recommendation

Solution 3 (Comprehensive Refactoring of specifyplus Bash Scripts) is the recommended approach. While it requires lifting the initial constraint against modifying the scripts and involves a substantial refactor, it is the only path that fully reconciles the specifyplus automation with the Phase II monorepo architectural requirements, leading to a truly automated and scalable SDD workflow for the Hackathon project.

This would require explicit authorization from the developers maintaining the specifyplus package.

[SARAMALI15792]

I am facing the same issue. I added the directory structure for the Phase-II Hackathon in the claude.md root file, but it is causing conflicts. When I run certain commands, such as /sp.xxx, the directory structure gets mixed up and creates errors.
If anyone has a solution for this, kindly share it here.

[hamzasaleem22]

I am experiencing the same problem. After adding the Phase-II Hackathon directory structure to the claude.md root file, it started creating conflicts. When I execute certain commands, such as /sp.xxx, the directory structure becomes inconsistent and leads to errors.
If anyone has a workaround or solution, please share it here.,hope so look for your kind response