SpecifyPlus Monorepo Conflict: Hackathon Phase II

Introduction: The Core of the Challenge

During the dynamic journey into Phase II of the Hackathon, we've encountered a pivotal conflict. This conflict emerges from the desired monorepo project structure detailed in the Hackathon II - Todo Spec-Driven Development.md document and the intrinsic operational mechanics of the specifyplus bash scripts. At its essence, this report elucidates the discord between the envisioned architectural framework and the existing toolset, providing a detailed analysis of its ramifications and proposing actionable solutions. This examination aims to forge a path toward a cohesive, automated, and scalable Spec-Driven Development (SDD) workflow that aligns with the Hackathon's architectural aspirations. This is important as specifyplus is intended to streamline the development process within the monorepo structure.

The Core Discrepancy

The heart of the matter lies in the divergent approaches to structuring the specs directory. The Hackathon document champions a meticulously organized specs directory, which houses feature specifications (specs/features/<short-name>.md) alongside associated planning and task artifacts (specs/features/<short-name>/). This structure is intended to be managed and governed by the .spec-kit/config.yaml file. In stark contrast, the specifyplus bash scripts, particularly those responsible for feature creation and path derivation (create-new-feature.sh and common.sh), are intrinsically linked to a rigid specs/<branch-name>/ directory structure. This means the default behavior of the tools does not inherently support the desired monorepo structure. For instance, a new feature named task-crud-web would typically result in a structure like specs/001-task-crud-web/spec.md. The result is a divergence that disrupts the intended workflow. This is why understanding the current structure is important, as it directly affects how we build and maintain the project’s specifications. The monorepo structure is designed to foster a well-organized and maintainable codebase.

The Impact of This Discrepancy

The variance between the planned monorepo structure and the current tool behavior generates a ripple effect of challenges, creating significant hurdles in the development workflow. Each issue underscores the need for a solution that seamlessly integrates the desired structure with the existing tools.

Manual Intervention and Its Ramifications

The most immediate consequence is the necessity for manual intervention. When a developer utilizes specifyplus commands to generate new files, the output does not inherently conform to the desired monorepo structure. This gap forces developers to manually move files and directories, such as relocating spec.md files from specs/<branch-name>/spec.md to specs/features/<short-name>.md. This manual process introduces inefficiencies and the potential for errors, significantly detracting from the automation benefits that specifyplus is designed to provide. This defeats the goal of streamlined SDD practices.

Command Failures and Workflow Disruptions

Subsequent specifyplus commands, such as /sp.plan, /sp.tasks, and others, frequently fail due to the mismatch in file locations. These commands depend on common.sh to locate or create artifact files in the specs/<branch-name>/ structure. Because the files have been moved, or the structure doesn't exist in the first place, these commands are unable to operate as intended. This disruption prevents a seamless workflow, forcing users to troubleshoot and correct the command's actions, leading to a fragmented and less efficient development process. Understanding the specific command failures is crucial to pinpointing the root cause.

Degradation of Automation and Strictness Violation

At its core, specifyplus is built to automate the SDD workflow. However, the requirement for manual corrections severely diminishes this automation. The AI agent, designed to follow the established steps, is forced to engage in manual interventions, which impedes the overall development rhythm. Furthermore, the discrepancy hinders the strict adherence to the documented workflow for generating specifications, plans, and tasks. This deviation from the established procedure can lead to inconsistencies and inefficiencies, reducing the intended strictness.

Root Cause Analysis: The Core of the Issue

The root cause of these issues is embedded within the path resolution mechanism of the specifyplus bash scripts, specifically within the common.sh and create-new-feature.sh scripts. These scripts are crucial for the creation of features and the generation of artifacts. The core problem lies in how these scripts determine where to store and retrieve files. Understanding the path resolution mechanism is key to resolving the conflicts.

The get_feature_paths Bottleneck

The get_feature_paths function within common.sh is the cornerstone of path resolution. Used by almost all specifyplus commands, it relies on get_current_branch. This function obtains the Git branch name, such as 001-task-crud-web, and uses it to construct all artifact paths. This rigid approach hardcodes paths like FEATURE_DIR='specs/$current_branch' and FEATURE_SPEC='$feature_dir/spec.md', leading to a tight coupling of file paths with the branch name. This design choice prevents flexibility and hinders the ability to adopt a more flexible structure such as the monorepo approach.

create-new-feature.sh: A Key Player in the Conflict

The create-new-feature.sh script directly utilizes the output of get_feature_paths to generate the initial directories and specification files. The script creates the initial directories and specifications based on the specs/<branch-name>/ structure. This method, while functional in its original design, directly conflicts with the desired monorepo structure. The script is also responsible for setting up the initial file structures for new features, making it a critical point of conflict.

The Ignored Configuration: .spec-kit/config.yaml

Currently, the specifyplus bash scripts neither read nor utilize the .spec-kit/config.yaml file. This is a missed opportunity, as the configuration file is designed to dynamically determine feature and artifact locations. This means the scripts cannot adapt to the flexibility and customization offered by the config file. By incorporating the .spec-kit/config.yaml file, the scripts could dynamically adapt to different project structures.

Possible Solutions: Navigating the Options

Addressing the monorepo structure conflict necessitates a clear evaluation of potential solutions. Each option presents its own set of trade-offs, and choosing the right one requires carefully considering the long-term goals and architectural vision of the project. These solutions range from manual workarounds to comprehensive refactoring of the bash scripts.

Solution 1: Manual Workarounds (Current Practice)

This approach involves continuing the existing practices: executing specifyplus commands for side effects like branch creation but manually managing all file creation and movement to conform to the monorepo structure. This means manually moving spec.md files, creating directories for plans and tasks, and populating them. This method, while preserving the integrity of the specifyplus scripts, introduces significant inefficiencies and manual overhead. While it adheres to the initial