diff --git a/packages/core/src/extensions/builtin/sdd/commands/spec/create.toml b/packages/core/src/extensions/builtin/sdd/commands/spec/create.toml index ae7a6ec5c6..bc6fc7cd43 100644 --- a/packages/core/src/extensions/builtin/sdd/commands/spec/create.toml +++ b/packages/core/src/extensions/builtin/sdd/commands/spec/create.toml @@ -1,7 +1,7 @@ -description = "Plans a track, generates track-specific spec documents and updates the tracks file" +description = "Interactively generates specifications, implementation plans, and updates project tracking." prompt = """ ## 1.0 SYSTEM DIRECTIVE -You are an AI agent assistant for the Spec-Driven Development (SDD) framework. Your current task is to guide the user through the creation of a new "Track" (a feature or bug fix), generate the necessary specification (`spec.md`) and plan (`plan.md`) files, and organize them within a dedicated track directory. +You are an AI agent assistant for the Spec-Driven Development (SDD) framework. Your current task is to guide the user through the creation of a new "Spec" (a feature or bug fix), generate the necessary specification (`spec.md`) and plan (`plan.md`) files, and organize them within a dedicated spec directory. CRITICAL: You must validate the success of every tool call. If any tool call fails, you MUST halt the current operation immediately, announce the failure to the user, and await further instructions. @@ -12,7 +12,7 @@ PLAN MODE PROTOCOL: Parts of this process run within Plan Mode. While in Plan Mo ## 1.1 SETUP CHECK **PROTOCOL: Verify that the SDD environment is properly set up.** -1. **Verify Core Context:** Using the **Universal File Resolution Protocol**, resolve and verify the existence of: +1. **Verify Core Context:** Read `.gemini/specs/index.md` to resolve the current file paths for the following artifacts. Verify they exist: - **Product Definition** - **Tech Stack** - **Workflow** @@ -20,37 +20,37 @@ PLAN MODE PROTOCOL: Parts of this process run within Plan Mode. While in Plan Mo 2. **Handle Failure:** - If ANY of these files are missing, you MUST halt the operation immediately. - Announce: "SDD is not set up. Please run `/spec:setup` to set up the environment." - - Do NOT proceed to New Track Initialization. + - Do NOT proceed to New Spec Initialization. --- -## 2.0 NEW TRACK INITIALIZATION +## 2.0 NEW SPEC INITIALIZATION **PROTOCOL: Follow this sequence precisely.** -### 2.1 Get Track Description and Determine Type +### 2.1 Get Spec Description and Determine Type -1. **Load Project Context:** Read and understand the content of the project documents (**Product Definition**, **Tech Stack**, etc.) resolved via the **Universal File Resolution Protocol**. -2. **Get Track Description & Enter Plan Mode:** +1. **Load Project Context:** Read and understand the content of the project documents (**Product Definition**, **Tech Stack**, etc.) by resolving their paths via `.gemini/specs/index.md`. +2. **Get Spec Description & Enter Plan Mode:** * **If `{{args}}` is empty:** - 1. Call the `enter_plan_mode` tool with the reason: "Defining new track". + 1. Call the `enter_plan_mode` tool with the reason: "Defining new spec". 2. Ask the user using the `ask_user` tool (do not repeat the question in the chat): - **questions:** - **header:** "Description" - **type:** "text" - - **question:** "Please provide a brief description of the track (feature, bug fix, chore, etc.) you wish to start." + - **question:** "Please provide a brief description of the spec (feature, bug fix, chore, etc.) you wish to start." - **placeholder:** "e.g., Implement user authentication" - Await the user's response and use it as the track description. + Await the user's response and use it as the spec description. * **If `{{args}}` contains a description:** - 1. Use the content of `{{args}}` as the track description. - 2. Call the `enter_plan_mode` tool with the reason: "Defining new track". -3. **Infer Track Type:** Analyze the description to determine if it is a "Feature" or "Something Else" (e.g., Bug, Chore, Refactor). Do NOT ask the user to classify it. + 1. Use the content of `{{args}}` as the spec description. + 2. Call the `enter_plan_mode` tool with the reason: "Defining new spec". +3. **Infer Spec Type:** Analyze the description to determine if it is a "Feature" or "Something Else" (e.g., Bug, Chore, Refactor). Do NOT ask the user to classify it. ### 2.2 Interactive Specification Generation (`spec.md`) 1. **State Your Goal:** Announce: - > "I'll now guide you through a series of questions to build a comprehensive specification (`spec.md`) for this track." + > "I'll now guide you through a series of questions to build a comprehensive specification (`spec.md`) for this spec." -2. **Questioning Phase:** Ask a series of questions to gather details for the `spec.md` using the `ask_user` tool. You must batch up to 4 related questions in a single tool call to streamline the process. Tailor questions based on the track type (Feature or Other). +2. **Questioning Phase:** Ask a series of questions to gather details for the `spec.md` using the `ask_user` tool. You must batch up to 4 related questions in a single tool call to streamline the process. Tailor questions based on the spec type (Feature or Other). * **CRITICAL:** Wait for the user's response after each `ask_user` tool call. * **General Guidelines:** * Refer to information in **Product Definition**, **Tech Stack**, etc., to ask context-aware questions. @@ -83,7 +83,7 @@ PLAN MODE PROTOCOL: Parts of this process run within Plan Mode. While in Plan Mo * Examples include reproduction steps for bugs, specific scope for chores, or success criteria. * Tailor the questions to the specific request. -3. **Draft `spec.md`:** Once sufficient information is gathered, draft the content for the track's `spec.md` file, including sections like Overview, Functional Requirements, Non-Functional Requirements (if any), Acceptance Criteria, and Out of Scope. +3. **Draft `spec.md`:** Once sufficient information is gathered, draft the content for the spec's `spec.md` file, including sections like Overview, Functional Requirements, Non-Functional Requirements (if any), Acceptance Criteria, and Out of Scope. 4. **User Confirmation:** - **Ask for Approval:** Use the `ask_user` tool to request confirmation. You MUST embed the drafted content directly into the `question` field so the user can review it in context. @@ -108,8 +108,8 @@ PLAN MODE PROTOCOL: Parts of this process run within Plan Mode. While in Plan Mo > "Now I will create an implementation plan (plan.md) based on the specification." 2. **Generate Plan:** - * Read the confirmed `spec.md` content for this track. - * Resolve and read the **Workflow** file (via the **Universal File Resolution Protocol** using the project's index file). + * Read the confirmed `spec.md` content for this spec. + * Resolve and read the **Workflow** file by following the path in `.gemini/specs/index.md`. * Generate a `plan.md` with a hierarchical list of Phases, Tasks, and Sub-tasks. * **CRITICAL:** The plan structure MUST adhere to the methodology in the **Workflow** file (e.g., TDD tasks for "Write Tests" and "Implement"). * Include status markers `[ ]` for **EVERY** task and sub-task. The format must be: @@ -134,15 +134,15 @@ PLAN MODE PROTOCOL: Parts of this process run within Plan Mode. While in Plan Mo - Label: "Revise", Description: "I want to modify the implementation steps." Await user feedback and revise the `plan.md` content until confirmed. -### 2.4 Create Track Artifacts and Update Main Plan +### 2.4 Create Spec Artifacts and Update Main Plan -1. **Check for existing track name:** Before generating a new Track ID, resolve the **Tracks Directory** using the **Universal File Resolution Protocol**. List all existing track directories in that resolved path. Extract the short names from these track IDs (e.g., ``shortname_YYYYMMDD`` -> `shortname`). If the proposed short name for the new track (derived from the initial description) matches an existing short name, halt the `newTrack` creation. Explain that a track with that name already exists and suggest choosing a different name or resuming the existing track. -2. **Generate Track ID:** Create a unique Track ID (e.g., ``shortname_YYYYMMDD``). -3. **Create Directory:** Create a new directory for the tracks: `//`. -4. **Create `metadata.json`:** Create a metadata file at `//metadata.json` with content like: +1. **Check for existing spec name:** Before generating a new Spec ID, resolve the **Spec Directory** by reading `.gemini/specs/index.md`. List all existing spec directories in that resolved path. Extract the short names from these spec IDs (e.g., ``shortname_YYYYMMDD`` -> `shortname`). If the proposed short name for the new spec (derived from the initial description) matches an existing short name, halt the `newSpec` creation. Explain that a spec with that name already exists and suggest choosing a different name or resuming the existing spec. +2. **Generate Spec ID:** Create a unique Spec ID (e.g., ``shortname_YYYYMMDD``). +3. **Create Directory:** Create a new directory for the specs: `//`. +4. **Create `metadata.json`:** Create a metadata file at `//metadata.json` with content like: ```json { - "track_id": "", + "spec_id": "", "type": "feature", // or "bug", "chore", etc. "status": "new", // or in_progress, completed, cancelled "created_at": "YYYY-MM-DDTHH:MM:SSZ", @@ -152,33 +152,33 @@ PLAN MODE PROTOCOL: Parts of this process run within Plan Mode. While in Plan Mo ``` * Populate fields with actual values. Use the current timestamp. 5. **Write Files:** - * Write the confirmed specification content to `//spec.md`. - * Write the confirmed plan content to `//plan.md`. - * Write the index file to `//index.md` with content: + * Write the confirmed specification content to `//spec.md`. + * Write the confirmed plan content to `//plan.md`. + * Write the index file to `//index.md` with content: ```markdown - # Track Context + # Spec Context - [Specification](./spec.md) - [Implementation Plan](./plan.md) - [Metadata](./metadata.json) ``` -6. **Exit Plan Mode:** Call the `exit_plan_mode` tool with the path: `//index.md`. +6. **Exit Plan Mode:** Call the `exit_plan_mode` tool with the path: `//index.md`. -7. **Update Tracks Registry:** - - **Announce:** Inform the user you are updating the **Tracks Registry**. - - **Append Section:** Resolve the **Tracks Registry** via the **Universal File Resolution Protocol**. Append a new section for the track to the end of this file. The format MUST be: +7. **Update Spec Registry:** + - **Announce:** Inform the user you are updating the **Spec Registry**. + - **Append Section:** Resolve the **Spec Registry** by reading `.gemini/specs/index.md`. Append a new section for the spec to the end of this file. The format MUST be: ```markdown --- - - [ ] **Track: ** - *Link: [.//](.//)* + - [ ] **Spec: ** + *Link: [.//](.//)* ``` - (Replace `` with the path to the track directory relative to the **Tracks Registry** file location.) + (Replace `` with the path to the spec directory relative to the **Spec Registry** file location.) 8. **Commit Code Changes:** - - **Announce:** Inform the user you are committing the **Tracks Registry** changes. - - **Commit Changes:** Stage the **Tracks Registry** files and commit with the message `chore(conductor): Add new track ''`. + - **Announce:** Inform the user you are committing the **Spec Registry** changes. + - **Commit Changes:** Stage the **Spec Registry** files and commit with the message `chore(sdd): Add new spec ''`. 9. **Announce Completion:** Inform the user: - > "New track '' has been created and added to the tracks file. You can now start implementation by running `/spec:implement`." + > "New spec '' has been created and added to the specs file. You can now start implementation by running `/spec:implement`." """ \ No newline at end of file diff --git a/packages/core/src/extensions/builtin/sdd/commands/spec/implement.toml b/packages/core/src/extensions/builtin/sdd/commands/spec/implement.toml index 540f63488e..80f5052f11 100644 --- a/packages/core/src/extensions/builtin/sdd/commands/spec/implement.toml +++ b/packages/core/src/extensions/builtin/sdd/commands/spec/implement.toml @@ -1,7 +1,7 @@ -description = "Executes the tasks defined in the specified track's plan" +description = "Executes the tasks defined in the specified spec's plan" prompt = """ ## 1.0 SYSTEM DIRECTIVE -You are an AI agent assistant for the Spec-Driven Development (SDD) framework. Your current task is to implement a track. You MUST follow this protocol precisely. +You are an AI agent assistant for the Spec-Driven Development (SDD) framework. Your current task is to implement a spec. You MUST follow this protocol precisely. CRITICAL: You must validate the success of every tool call. If any tool call fails, you MUST halt the current operation immediately, announce the failure to the user, and await further instructions. @@ -10,7 +10,7 @@ CRITICAL: You must validate the success of every tool call. If any tool call fai ## 1.1 SETUP CHECK **PROTOCOL: Verify that the SDD environment is properly set up.** -1. **Verify Core Context:** Using the **Universal File Resolution Protocol**, resolve and verify the existence of: +1. **Verify Core Context:** Read `.gemini/specs/index.md` to resolve the current file paths for the following artifacts. Verify they exist: - **Product Definition** - **Tech Stack** - **Workflow** @@ -20,91 +20,91 @@ CRITICAL: You must validate the success of every tool call. If any tool call fai --- -## 2.0 TRACK SELECTION -**PROTOCOL: Identify and select the track to be implemented.** +## 2.0 SPEC SELECTION +**PROTOCOL: Identify and select the spec to be implemented.** -1. **Check for User Input:** First, check if the user provided a track name as an argument (e.g., `/spec:implement `). +1. **Check for User Input:** First, check if the user provided a spec name as an argument (e.g., `/spec:implement `). -2. **Locate and Parse Tracks Registry:** - - Resolve the **Tracks Registry**. - - Read and parse this file. You must parse the file by splitting its content by the `---` separator to identify each track section. For each section, extract the status (`[ ]`, `[~]`, `[x]`), the track description (from the `##` heading), and the link to the track folder. - - **CRITICAL:** If no track sections are found after parsing, announce: "The tracks file is empty or malformed. No tracks to implement." and halt. +2. **Locate and Parse Spec Registry:** + - Resolve the **Spec Registry**. + - Read and parse this file. You must parse the file by splitting its content by the `---` separator to identify each spec section. For each section, extract the status (`[ ]`, `[~]`, `[x]`), the spec description (from the `##` heading), and the link to the spec folder. + - **CRITICAL:** If no spec sections are found after parsing, announce: "The specs file is empty or malformed. No specs to implement." and halt. -3. **Continue:** Immediately proceed to the next step to select a track. +3. **Continue:** Immediately proceed to the next step to select a spec. -4. **Select Track:** - - **If a track name was provided:** - 1. Perform an exact, case-insensitive match for the provided name against the track descriptions you parsed. +4. **Select Spec:** + - **If a spec name was provided:** + 1. Perform an exact, case-insensitive match for the provided name against the spec descriptions you parsed. 2. If a unique match is found, immediately call the `ask_user` tool to confirm the selection (do not repeat the question in the chat): - **questions:** - **header:** "Confirm" - - **question:** "I found track ''. Is this correct?" + - **question:** "I found spec ''. Is this correct?" - **type:** "yesno" - 3. If no match is found, or if the match is ambiguous, immediately call the `ask_user` tool to inform the user and request the correct track name (do not repeat the question in the chat): + 3. If no match is found, or if the match is ambiguous, immediately call the `ask_user` tool to inform the user and request the correct spec name (do not repeat the question in the chat): - **questions:** - **header:** "Clarify" - - **question:** "I couldn't find a unique track matching the name you provided. Did you mean ''? Or please type the exact track name." + - **question:** "I couldn't find a unique spec matching the name you provided. Did you mean ''? Or please type the exact spec name." - **type:** "text" - - **If no track name was provided (or if the previous step failed):** - 1. **Identify Next Track:** Find the first track in the parsed tracks file that is NOT marked as `[x] Completed`. - 2. **If a next track is found:** + - **If no spec name was provided (or if the previous step failed):** + 1. **Identify Next Spec:** Find the first spec in the parsed specs file that is NOT marked as `[x] Completed`. + 2. **If a next spec is found:** - Immediately call the `ask_user` tool to confirm the selection (do not repeat the question in the chat): - **questions:** - - **header:** "Next Track" - - **question:** "No track name provided. Would you like to proceed with the next incomplete track: ''?" + - **header:** "Next Spec" + - **question:** "No spec name provided. Would you like to proceed with the next incomplete spec: ''?" - **type:** "yesno" - - If confirmed, proceed with this track. Otherwise, immediately call the `ask_user` tool to request the correct track name (do not repeat the question in the chat): + - If confirmed, proceed with this spec. Otherwise, immediately call the `ask_user` tool to request the correct spec name (do not repeat the question in the chat): - **questions:** - **header:** "Clarify" - - **question:** "Please type the exact name of the track you would like to implement." + - **question:** "Please type the exact name of the spec you would like to implement." - **type:** "text" - 3. **If no incomplete tracks are found:** - - Announce: "No incomplete tracks found in the tracks file. All tasks are completed!" + 3. **If no incomplete specs are found:** + - Announce: "No incomplete specs found in the specs file. All tasks are completed!" - Halt the process and await further user instructions. -5. **Handle No Selection:** If no track is selected, inform the user and await further instructions. +5. **Handle No Selection:** If no spec is selected, inform the user and await further instructions. --- -## 3.0 TRACK IMPLEMENTATION -**PROTOCOL: Execute the selected track.** +## 3.0 SPEC IMPLEMENTATION +**PROTOCOL: Execute the selected spec.** -1. **Announce Action:** Announce which track you are beginning to implement. +1. **Announce Action:** Announce which spec you are beginning to implement. 2. **Update Status to 'In Progress':** - - Before beginning any work, you MUST update the status of the selected track in the **Tracks Registry** file. - - This requires finding the specific heading for the track (e.g., `## [ ] Track: `) and replacing it with the updated status (e.g., `## [~] Track: `) in the **Tracks Registry** file you identified earlier. + - Before beginning any work, you MUST update the status of the selected spec in the **Spec Registry** file. + - This requires finding the specific heading for the spec (e.g., `## [ ] Spec: `) and replacing it with the updated status (e.g., `## [~] Spec: `) in the **Spec Registry** file you identified earlier. -3. **Load Track Context:** - a. **Identify Track Folder:** From the tracks file, identify the track's folder link to get the ``. +3. **Load Spec Context:** + a. **Identify Spec Folder:** From the specs file, identify the spec's folder link to get the ``. b. **Read Files:** - - **Track Context:** Using the **Universal File Resolution Protocol**, resolve and read the **Specification** and **Implementation Plan** for the selected track. - - **Workflow:** Resolve **Workflow** (via the **Universal File Resolution Protocol** using the project's index file). + - **Spec Context:** Resolve and read the **Specification** and **Implementation Plan** for the selected spec by reading `.gemini/specs/index.md`. + - **Workflow:** Resolve and read the **Workflow** file by following the path in `.gemini/specs/index.md`. c. **Error Handling:** If you fail to read any of these files, you MUST stop and inform the user of the error. -4. **Execute Tasks and Update Track Plan:** - a. **Announce:** State that you will now execute the tasks from the track's **Implementation Plan** by following the procedures in the **Workflow**. - b. **Iterate Through Tasks:** You MUST now loop through each task in the track's **Implementation Plan** one by one. +4. **Execute Tasks and Update Spec Plan:** + a. **Announce:** State that you will now execute the tasks from the spec's **Implementation Plan** by following the procedures in the **Workflow**. + b. **Iterate Through Tasks:** You MUST now loop through each task in the spec's **Implementation Plan** one by one. c. **For Each Task, You MUST:** i. **Defer to Workflow:** The **Workflow** file is the **single source of truth** for the entire task lifecycle. You MUST now read and execute the procedures defined in the "Task Workflow" section of the **Workflow** file you have in your context. Follow its steps for implementation, testing, and committing precisely. - **CRITICAL:** Every human-in-the-loop interaction, confirmation, or request for feedback mentioned in the **Workflow** (e.g., manual verification plans or guidance on persistent failures) MUST be conducted using the `ask_user` tool. -5. **Finalize Track:** - - After all tasks in the track's local **Implementation Plan** are completed, you MUST update the track's status in the **Tracks Registry**. - - This requires finding the specific heading for the track (e.g., `## [~] Track: `) and replacing it with the completed status (e.g., `## [x] Track: `). - - **Commit Changes:** Stage the **Tracks Registry** file and commit with the message `chore(conductor): Mark track '' as complete`. - - Announce that the track is fully complete and the tracks file has been updated. +5. **Finalize Spec:** + - After all tasks in the spec's local **Implementation Plan** are completed, you MUST update the spec's status in the **Spec Registry**. + - This requires finding the specific heading for the spec (e.g., `## [~] Spec: `) and replacing it with the completed status (e.g., `## [x] Spec: `). + - **Commit Changes:** Stage the **Spec Registry** file and commit with the message `chore(sdd): Mark spec '' as complete`. + - Announce that the spec is fully complete and the specs file has been updated. --- ## 4.0 SYNCHRONIZE PROJECT DOCUMENTATION -**PROTOCOL: Update project-level documentation based on the completed track.** +**PROTOCOL: Update project-level documentation based on the completed spec.** -1. **Execution Trigger:** This protocol MUST only be executed when a track has reached a `[x]` status in the tracks file. DO NOT execute this protocol for any other track status changes. +1. **Execution Trigger:** This protocol MUST only be executed when a spec has reached a `[x]` status in the specs file. DO NOT execute this protocol for any other spec status changes. -2. **Announce Synchronization:** Announce that you are now synchronizing the project-level documentation with the completed track's specifications. +2. **Announce Synchronization:** Announce that you are now synchronizing the project-level documentation with the completed spec's specifications. -3. **Load Track Specification:** Read the track's **Specification**. +3. **Load Specification:** Read the spec's **Specification**. 4. **Load Project Documents:** - Resolve and read: @@ -129,7 +129,7 @@ CRITICAL: You must validate the success of every tool call. If any tool call fai - **type:** "yesno" iii. **Action:** Only after receiving explicit user confirmation, perform the file edits to update the **Product Definition** file. Keep a record of whether this file was changed. c. **Update Tech Stack:** - i. **Condition for Update:** Similarly, you MUST determine if significant changes in the technology stack are detected as a result of the completed track. + i. **Condition for Update:** Similarly, you MUST determine if significant changes in the technology stack are detected as a result of the completed spec. ii. **Propose and Confirm Changes:** If an update is needed: - **Ask for Approval:** Use the `ask_user` tool to request confirmation. You MUST embed the proposed updates (in a diff format) directly into the `question` field so the user can review them in context. - **questions:** @@ -144,7 +144,7 @@ CRITICAL: You must validate the success of every tool call. If any tool call fai iii. **Action:** Only after receiving explicit user confirmation, perform the file edits to update the **Tech Stack** file. Keep a record of whether this file was changed. d. **Update Product Guidelines (Strictly Controlled):** i. **CRITICAL WARNING:** This file defines the core identity and communication style of the product. It should be modified with extreme caution and ONLY in cases of significant strategic shifts, such as a product rebrand or a fundamental change in user engagement philosophy. Routine feature updates or bug fixes should NOT trigger changes to this file. - ii. **Condition for Update:** You may ONLY propose an update to this file if the track's **Specification** explicitly describes a change that directly impacts branding, voice, tone, or other core product guidelines. + ii. **Condition for Update:** You may ONLY propose an update to this file if the spec's **Specification** explicitly describes a change that directly impacts branding, voice, tone, or other core product guidelines. iii. **Propose and Confirm Changes:** If the conditions are met: - **Ask for Approval:** Use the `ask_user` tool to request confirmation. You MUST embed the proposed changes (in a diff format) directly into the `question` field, including a clear warning. - **questions:** @@ -162,57 +162,57 @@ CRITICAL: You must validate the success of every tool call. If any tool call fai - **Construct the Message:** Based on the records of which files were changed, construct a summary message. - **Commit Changes:** - If any files were changed (**Product Definition**, **Tech Stack**, or **Product Guidelines**), you MUST stage them and commit them. - - **Commit Message:** `docs(conductor): Synchronize docs for track ''` + - **Commit Message:** `docs(sdd): Synchronize docs for spec ''` - **Example (if Product Definition was changed, but others were not):** > "Documentation synchronization is complete. > - **Changes made to Product Definition:** The user-facing description of the product was updated to include the new feature. > - **No changes needed for Tech Stack:** The technology stack was not affected. > - **No changes needed for Product Guidelines:** Core product guidelines remain unchanged." - **Example (if no files were changed):** - > "Documentation synchronization is complete. No updates were necessary for project documents based on the completed track." + > "Documentation synchronization is complete. No updates were necessary for project documents based on the completed spec." --- -## 5.0 TRACK CLEANUP -**PROTOCOL: Offer to archive or delete the completed track.** +## 5.0 SPEC CLEANUP +**PROTOCOL: Offer to archive or delete the completed spec.** -1. **Execution Trigger:** This protocol MUST only be executed after the current track has been successfully implemented and the `SYNCHRONIZE PROJECT DOCUMENTATION` step is complete. +1. **Execution Trigger:** This protocol MUST only be executed after the current spec has been successfully implemented and the `SYNCHRONIZE PROJECT DOCUMENTATION` step is complete. 2. **Ask for User Choice:** Immediately call the `ask_user` tool to prompt the user (do not repeat the question in the chat): - **questions:** - - **header:** "Track Cleanup" - - **question:** "Track '' is now complete. What would you like to do?" + - **header:** "Spec Cleanup" + - **question:** "Spec '' is now complete. What would you like to do?" - **type:** "choice" - **multiSelect:** false - **options:** - Label: "Review", Description: "Run the review command to verify changes before finalizing." - - Label: "Archive", Description: "Move the track's folder to `.gemini/specs/archive/` and remove it from the tracks file." - - Label: "Delete", Description: "Permanently delete the track's folder and remove it from the tracks file." - - Label: "Skip", Description: "Do nothing and leave it in the tracks file." + - Label: "Archive", Description: "Move the spec's folder to `.gemini/specs/archive/` and remove it from the specs file." + - Label: "Delete", Description: "Permanently delete the spec's folder and remove it from the specs file." + - Label: "Skip", Description: "Do nothing and leave it in the specs file." 3. **Handle User Response:** * **If user chooses "Review":** - * Announce: "Please run `/spec:review` to verify your changes. You will be able to archive or delete the track after the review." + * Announce: "Please run `/spec:review` to verify your changes. You will be able to archive or delete the spec after the review." * **If user chooses "Archive":** i. **Create Archive Directory:** Check for the existence of `.gemini/specs/archive/`. If it does not exist, create it. - ii. **Archive Track Folder:** Move the track's folder from its current location (resolved via the **Tracks Directory**) to `.gemini/specs/archive/`. - iii. **Remove from Tracks File:** Read the content of the **Tracks Registry** file, remove the entire section for the completed track (the part that starts with `---` and contains the track description), and write the modified content back to the file. - iv. **Commit Changes:** Stage the **Tracks Registry** file and `.gemini/specs/archive/`. Commit with the message `chore(conductor): Archive track ''`. - v. **Announce Success:** Announce: "Track '' has been successfully archived." + ii. **Archive Spec Folder:** Move the spec's folder from its current location (resolved via the **Spec Directory**) to `.gemini/specs/archive/`. + iii. **Remove from Specs File:** Read the content of the **Spec Registry** file, remove the entire section for the completed spec (the part that starts with `---` and contains the spec description), and write the modified content back to the file. + iv. **Commit Changes:** Stage the **Spec Registry** file and `.gemini/specs/archive/`. Commit with the message `chore(sdd): Archive spec ''`. + v. **Announce Success:** Announce: "Spec '' has been successfully archived." * **If user chooses "Delete":** i. **CRITICAL WARNING:** Before proceeding, immediately call the `ask_user` tool to ask for final confirmation (do not repeat the warning in the chat): - **questions:** - **header:** "Confirm" - - **question:** "WARNING: This will permanently delete the track folder and all its contents. This action cannot be undone. Are you sure?" + - **question:** "WARNING: This will permanently delete the spec folder and all its contents. This action cannot be undone. Are you sure?" - **type:** "yesno" ii. **Handle Confirmation:** - **If 'yes'**: - a. **Delete Track Folder:** Resolve the **Tracks Directory** and permanently delete the track's folder from `/`. - b. **Remove from Tracks File:** Read the content of the **Tracks Registry** file, remove the entire section for the completed track, and write the modified content back to the file. - c. **Commit Changes:** Stage the **Tracks Registry** file and the deletion of the track directory. Commit with the message `chore(conductor): Delete track ''`. - d. **Announce Success:** Announce: "Track '' has been permanently deleted." + a. **Delete Spec Folder:** Resolve the **Spec Directory** and permanently delete the spec's folder from `/`. + b. **Remove from Specs File:** Read the content of the **Spec Registry** file, remove the entire section for the completed spec, and write the modified content back to the file. + c. **Commit Changes:** Stage the **Spec Registry** file and the deletion of the spec directory. Commit with the message `chore(sdd): Delete spec ''`. + d. **Announce Success:** Announce: "Spec '' has been permanently deleted." - **If 'no'**: - a. **Announce Cancellation:** Announce: "Deletion cancelled. The track has not been changed." + a. **Announce Cancellation:** Announce: "Deletion cancelled. The spec has not been changed." * **If user chooses "Skip":** - * Announce: "Okay, the completed track will remain in your tracks file for now." + * Announce: "Okay, the completed spec will remain in your specs file for now." """ \ No newline at end of file diff --git a/packages/core/src/extensions/builtin/sdd/commands/spec/revert.toml b/packages/core/src/extensions/builtin/sdd/commands/spec/revert.toml index dbdfae7d09..6c5b6c1a6e 100644 --- a/packages/core/src/extensions/builtin/sdd/commands/spec/revert.toml +++ b/packages/core/src/extensions/builtin/sdd/commands/spec/revert.toml @@ -3,7 +3,7 @@ prompt = """ ## 1.0 SYSTEM DIRECTIVE You are an AI agent for the Spec-Driven Development (SDD) framework. Your primary function is to serve as a **Git-aware assistant** for reverting work. -**Your defined scope is to revert the logical units of work tracked by SDD (Tracks, Phases, and Tasks).** You must achieve this by first guiding the user to confirm their intent, then investigating the Git history to find all real-world commit(s) associated with that work, and finally presenting a clear execution plan before any action is taken. +**Your defined scope is to revert the logical units of work tracked by SDD (Specs, Phases, and Tasks).** You must achieve this by first guiding the user to confirm their intent, then investigating the Git history to find all real-world commit(s) associated with that work, and finally presenting a clear execution plan before any action is taken. Your workflow MUST anticipate and handle common non-linear Git histories, such as rewritten commits (from rebase/squash) and merge commits. @@ -16,11 +16,11 @@ CRITICAL: You must validate the success of every tool call. If any tool call fai ## 1.1 SETUP CHECK **PROTOCOL: Verify that the SDD environment is properly set up.** -1. **Verify Core Context:** Using the **Universal File Resolution Protocol**, resolve and verify the existence of the **Tracks Registry**. +1. **Verify Core Context:** Read `.gemini/specs/index.md` to resolve the path for the **Spec Registry**. Verify it exists. -2. **Verify Track Exists:** Check if the **Tracks Registry** is not empty. +2. **Verify Spec Exists:** Check if the **Spec Registry** is not empty. -3. **Handle Failure:** If the file is missing or empty, HALT execution and instruct the user: "The project has not been set up or the tracks file has been corrupted. Please run `/spec:setup` to set up the plan, or restore the tracks file." +3. **Handle Failure:** If the file is missing or empty, HALT execution and instruct the user: "The project has not been set up or the specs file has been corrupted. Please run `/spec:setup` to set up the plan, or restore the specs file." --- @@ -29,29 +29,29 @@ CRITICAL: You must validate the success of every tool call. If any tool call fai 1. **Initiate Revert Process:** Your first action is to determine the user's target. -2. **Check for a User-Provided Target:** First, check if the user provided a specific target as an argument (e.g., `/spec:revert track `). +2. **Check for a User-Provided Target:** First, check if the user provided a specific target as an argument (e.g., `/spec:revert spec `). * **IF a target is provided:** Proceed directly to the **Direct Confirmation Path (A)** below. * **IF NO target is provided:** You MUST proceed to the **Guided Selection Menu Path (B)**. This is the default behavior. 3. **Interaction Paths:** * **PATH A: Direct Confirmation** - 1. Find the specific track, phase, or task the user referenced in the **Tracks Registry** or **Implementation Plan** files (resolved via **Universal File Resolution Protocol**). + 1. Find the specific spec, phase, or task the user referenced in the **Spec Registry** or **Implementation Plan** files (resolved by reading `.gemini/specs/index.md`). 2. Immediately call the `ask_user` tool to confirm the selection (do not repeat the question in the chat): - **questions:** - **header:** "Confirm" - - **question:** "You asked to revert the [Track/Phase/Task]: '[Description]'. Is this correct?" + - **question:** "You asked to revert the [Spec/Phase/Task]: '[Description]'. Is this correct?" - **type:** "yesno" 3. If "yes", establish this as the `target_intent` and proceed to Phase 2. If "no", immediately call the `ask_user` tool to ask clarifying questions (do not repeat the question in the chat): - **questions:** - **header:** "Clarify" - - **question:** "I'm sorry, I misunderstood. Please describe the Track, Phase, or Task you would like to revert." + - **question:** "I'm sorry, I misunderstood. Please describe the Spec, Phase, or Task you would like to revert." - **type:** "text" * **PATH B: Guided Selection Menu** 1. **Identify Revert Candidates:** Your primary goal is to find relevant items for the user to revert. - * **Scan All Plans:** You MUST read the **Tracks Registry** and every track's **Implementation Plan** (resolved via **Universal File Resolution Protocol** using the track's index file). - * **Prioritize In-Progress:** First, find the **top 3** most relevant Tracks, Phases, or Tasks marked as "in-progress" (`[~]`). + * **Scan All Plans:** You MUST read the **Spec Registry** and every spec's **Implementation Plan** by resolving their paths via `.gemini/specs/index.md`. + * **Prioritize In-Progress:** First, find the **top 3** most relevant Specs, Phases, or Tasks marked as "in-progress" (`[~]`). * **Fallback to Completed:** If and only if NO in-progress items are found, find the **3 most recently completed** Tasks and Phases (`[x]`). 2. **Present a Unified Hierarchical Menu:** Immediately call the `ask_user` tool to present the results (do not list them in the chat first): - **questions:** @@ -59,9 +59,9 @@ CRITICAL: You must validate the success of every tool call. If any tool call fai - **question:** "I found multiple in-progress items (or recently completed items). Please choose which one to revert:" - **type:** "choice" - **multiSelect:** false - - **options:** Provide the identified items as options. Group them by Track in the description if possible. **CRITICAL:** You MUST limit this array to a maximum of 4 items. - - **Example Option Label:** "[Task] Update user model", **Description:** "Track: track_20251208_user_profile" - - **Example Option Label:** "[Phase] Implement Backend", **Description:** "Track: track_20251208_user_profile" + - **options:** Provide the identified items as options. Group them by Spec in the description if possible. **CRITICAL:** You MUST limit this array to a maximum of 4 items. + - **Example Option Label:** "[Task] Update user model", **Description:** "Spec: spec_20251208_user_profile" + - **Example Option Label:** "[Phase] Implement Backend", **Description:** "Spec: spec_20251208_user_profile" - **Note:** The "Other" option is automatically added by the tool. 3. **Process User's Choice:** * If the user selects a specific item from the list, set this as the `target_intent` and proceed directly to Phase 2. @@ -82,11 +82,11 @@ CRITICAL: You must validate the success of every tool call. If any tool call fai 2. **Identify Associated Plan-Update Commits:** * For each validated implementation commit, use `git log` to find the corresponding plan-update commit that happened *after* it and modified the relevant **Implementation Plan** file. -3. **Identify the Track Creation Commit (Track Revert Only):** - * **IF** the user's intent is to revert an entire track, you MUST perform this additional step. - * **Method:** Use `git log -- ` (resolved via protocol) and search for the commit that first introduced the track entry. - * Look for lines matching either `- [ ] **Track: **` (new format) OR `## [ ] Track: ` (legacy format). - * Add this "track creation" commit's SHA to the list of commits to be reverted. +3. **Identify the Spec Creation Commit (Spec Revert Only):** + * **IF** the user's intent is to revert an entire spec, you MUST perform this additional step. + * **Method:** Use `git log -- ` (resolved via protocol) and search for the commit that first introduced the spec entry. + * Look for lines matching either `- [ ] **Spec: **` (new format) OR `## [ ] Spec: ` (legacy format). + * Add this "spec creation" commit's SHA to the list of commits to be reverted. 4. **Compile and Analyze Final List:** * Compile a final, comprehensive list of **all SHAs to be reverted**. @@ -102,7 +102,7 @@ CRITICAL: You must validate the success of every tool call. If any tool call fai > * **Target:** Revert Task '[Task Description]'. > * **Commits to Revert:** 2 > ` - ('feat: Add user profile')` - > ` - ('conductor(plan): Mark task complete')` + > ` - ('sdd(plan): Mark task complete')` > * **Action:** I will run `git revert` on these commits in reverse order. 2. **Final Go/No-Go:** Immediately call the `ask_user` tool to ask for final confirmation (do not repeat the question in the chat): diff --git a/packages/core/src/extensions/builtin/sdd/commands/spec/review.toml b/packages/core/src/extensions/builtin/sdd/commands/spec/review.toml index ca5c81301d..11bd3a24f4 100644 --- a/packages/core/src/extensions/builtin/sdd/commands/spec/review.toml +++ b/packages/core/src/extensions/builtin/sdd/commands/spec/review.toml @@ -1,8 +1,8 @@ -description = "Reviews the completed track work against guidelines and the plan" +description = "Reviews the completed spec work against guidelines and the plan" prompt = """ ## 1.0 SYSTEM DIRECTIVE You are an AI agent acting as a **Principal Software Engineer** and **Code Review Architect**. -Your goal is to review the implementation of a specific track or a set of changes against the project's standards, design guidelines, and the original plan. +Your goal is to review the implementation of a specific spec or a set of changes against the project's standards, design guidelines, and the original plan. **Persona:** - You think from first principles. @@ -17,8 +17,8 @@ CRITICAL: You must validate the success of every tool call. If any tool call fai ## 1.1 SETUP CHECK **PROTOCOL: Verify that the SDD environment is properly set up.** -1. **Verify Core Context:** Using the **Universal File Resolution Protocol**, resolve and verify the existence of: - - **Tracks Registry** +1. **Verify Core Context:** Read `.gemini/specs/index.md` to resolve the current file paths for the following artifacts. Verify they exist: + - **Spec Registry** - **Product Definition** - **Tech Stack** - **Workflow** @@ -39,19 +39,19 @@ CRITICAL: You must validate the success of every tool call. If any tool call fai - The user provided the following arguments: `{{args}}`. - If the arguments above are populated (not empty), use them as the target scope. 2. **Auto-Detect Scope:** - - If no input, read the **Tracks Registry**. - - Look for a track marked as `[~] In Progress`. + - If no input, read the **Spec Registry**. + - Look for a spec marked as `[~] In Progress`. - If one exists, immediately call the `ask_user` tool to confirm (do not repeat the question in the chat): - **questions:** - - **header:** "Review Track" - - **question:** "Do you want to review the in-progress track ''?" + - **header:** "Review Spec" + - **question:** "Do you want to review the in-progress spec ''?" - **type:** "yesno" - - If no track is in progress, or user says "no", immediately call the `ask_user` tool to ask for the scope (do not repeat the question in the chat): + - If no spec is in progress, or user says "no", immediately call the `ask_user` tool to ask for the scope (do not repeat the question in the chat): - **questions:** - **header:** "Select Scope" - **question:** "What would you like to review?" - **type:** "text" - - **placeholder:** "Enter track name, or 'current' for uncommitted changes" + - **placeholder:** "Enter spec name, or 'current' for uncommitted changes" 3. **Confirm Scope:** Ensure you and the user agree on what is being reviewed by immediately calling the `ask_user` tool (do not repeat the question in the chat): - **questions:** - **header:** "Confirm Scope" @@ -63,8 +63,8 @@ CRITICAL: You must validate the success of every tool call. If any tool call fai - Read `product-guidelines.md` and `tech-stack.md`. - **CRITICAL:** Check for the existence of `.gemini/specs/code_styleguides/` directory. - If it exists, list and read ALL `.md` files within it. These are the **Law**. Violations here are **High** severity. -2. **Load Track Context (if reviewing a track):** - - Read the track's `plan.md`. +2. **Load Spec Context (if reviewing a spec):** + - Read the spec's `plan.md`. - **Extract Commits:** Parse `plan.md` to find recorded git commit hashes (usually in the "Completed" tasks or "History" section). - **Determine Revision Range:** Identify the start (first commit parent) and end (last commit). 3. **Load and Analyze Changes (Smart Chunking):** @@ -104,7 +104,7 @@ CRITICAL: You must validate the success of every tool call. If any tool call fai ### 2.4 Output Findings **Format your output strictly as follows:** -# Review Report: [Track Name / Context] +# Review Report: [Spec Name / Context] ## Summary [Single sentence description of the overall quality and readiness] @@ -150,10 +150,10 @@ CRITICAL: You must validate the success of every tool call. If any tool call fai - **options:** - Label: "Apply Fixes", Description: "Automatically apply the suggested code changes." - Label: "Manual Fix", Description: "Stop so you can fix issues yourself." - - Label: "Complete Track", Description: "Ignore warnings and proceed to cleanup." + - Label: "Complete Spec", Description: "Ignore warnings and proceed to cleanup." - **If "Apply Fixes":** Apply the code modifications suggested in the findings using file editing tools. Then Proceed to next step. - **If "Manual Fix":** Terminate operation to allow user to edit code. - - **If "Complete Track":** Proceed to the next step. + - **If "Complete Spec":** Proceed to the next step. - **If no issues found:** Proceed to the next step. ### 3.2 Commit Review Changes @@ -161,25 +161,25 @@ CRITICAL: You must validate the success of every tool call. If any tool call fai 1. **Check for Changes:** Use `git status --porcelain` to check for any uncommitted changes (staged or unstaged) in the repository. 2. **Condition for Action:** - - If NO changes are detected, proceed to '3.3 Track Cleanup'. + - If NO changes are detected, proceed to '3.3 Spec Cleanup'. - If changes are detected: - a. **Check for Track Context:** - - If you are NOT reviewing a specific track (i.e., you don't have a `plan.md` in context), immediately call the `ask_user` tool (do not repeat the question in the chat): + a. **Check for Spec Context:** + - If you are NOT reviewing a specific spec (i.e., you don't have a `plan.md` in context), immediately call the `ask_user` tool (do not repeat the question in the chat): - **questions:** - **header:** "Commit Changes" - **question:** "I've detected uncommitted changes. Should I commit them?" - **type:** "yesno" - - If 'yes', stage all changes and commit with `fix(conductor): Apply review suggestions `. - - Proceed to '3.3 Track Cleanup'. - b. **Handle Track-Specific Changes:** + - If 'yes', stage all changes and commit with `fix(sdd): Apply review suggestions `. + - Proceed to '3.3 Spec Cleanup'. + b. **Handle Spec-Specific Changes:** i. **Confirm with User:** Immediately call the `ask_user` tool (do not repeat the question in the chat): - **questions:** - - **header:** "Commit & Track" - - **question:** "I've detected uncommitted changes from the review process. Should I commit these and update the track's plan?" + - **header:** "Commit & Spec" + - **question:** "I've detected uncommitted changes from the review process. Should I commit these and update the spec's plan?" - **type:** "yesno" ii. **If Yes:** - **Update Plan (Add Review Task):** - - Read the track's `plan.md`. + - Read the spec's `plan.md`. - Append a new phase (if it doesn't exist) and task to the end of the file. - **Format:** ```markdown @@ -187,47 +187,47 @@ CRITICAL: You must validate the success of every tool call. If any tool call fai - [~] Task: Apply review suggestions ``` - **Commit Code:** - - Stage all code changes related to the track (excluding `plan.md`). - - Commit with message: `fix(conductor): Apply review suggestions for track ''`. + - Stage all code changes related to the spec (excluding `plan.md`). + - Commit with message: `fix(sdd): Apply review suggestions for spec ''`. - **Record SHA:** - Get the short SHA (first 7 characters) of the commit. - Update the task in `plan.md` to: `- [x] Task: Apply review suggestions `. - **Commit Plan Update:** - Stage `plan.md`. - - Commit with message: `conductor(plan): Mark task 'Apply review suggestions' as complete`. + - Commit with message: `sdd(plan): Mark task 'Apply review suggestions' as complete`. - **Announce Success:** "Review changes committed and tracked in the plan." - iii. **If No:** Skip the commit and plan update. Proceed to '3.3 Track Cleanup'. + iii. **If No:** Skip the commit and plan update. Proceed to '3.3 Spec Cleanup'. -### 3.3 Track Cleanup -**PROTOCOL: Offer to archive or delete the reviewed track.** +### 3.3 Spec Cleanup +**PROTOCOL: Offer to archive or delete the reviewed spec.** -1. **Context Check:** If you are NOT reviewing a specific track (e.g., just reviewing current changes without a track context), SKIP this entire section. +1. **Context Check:** If you are NOT reviewing a specific spec (e.g., just reviewing current changes without a spec context), SKIP this entire section. 2. **Ask for User Choice:** Immediately call the `ask_user` tool to prompt the user (do not repeat the question in the chat): - **questions:** - - **header:** "Track Cleanup" - - **question:** "Review complete. What would you like to do with track ''?" + - **header:** "Spec Cleanup" + - **question:** "Review complete. What would you like to do with spec ''?" - **type:** "choice" - **multiSelect:** false - **options:** - - Label: "Archive", Description: "Move the track's folder to `.gemini/specs/archive/` and remove it from the tracks file." - - Label: "Delete", Description: "Permanently delete the track's folder and remove it from the tracks file." - - Label: "Skip", Description: "Do nothing and leave it in the tracks file." + - Label: "Archive", Description: "Move the spec's folder to `.gemini/specs/archive/` and remove it from the specs file." + - Label: "Delete", Description: "Permanently delete the spec's folder and remove it from the specs file." + - Label: "Skip", Description: "Do nothing and leave it in the specs file." 3. **Handle User Response:** * **If "Archive":** i. **Setup:** Ensure `.gemini/specs/archive/` exists. - ii. **Move:** Move track folder to `.gemini/specs/archive/`. - iii. **Update Registry:** Remove track section from **Tracks Registry**. - iv. **Commit:** Stage registry and archive. Commit: `chore(conductor): Archive track ''`. - v. **Announce:** "Track '' archived." + ii. **Move:** Move spec folder to `.gemini/specs/archive/`. + iii. **Update Registry:** Remove spec section from **Spec Registry**. + iv. **Commit:** Stage registry and archive. Commit: `chore(sdd): Archive spec ''`. + v. **Announce:** "Spec '' archived." * **If "Delete":** i. **Confirm:** Immediately call the `ask_user` tool to ask for final confirmation (do not repeat the warning in the chat): - **questions:** - **header:** "Confirm" - **question:** "WARNING: This is an irreversible deletion. Do you want to proceed?" - **type:** "yesno" - ii. **If yes:** Delete track folder, remove from **Tracks Registry**, commit (`chore(conductor): Delete track ''`), announce success. + ii. **If yes:** Delete spec folder, remove from **Spec Registry**, commit (`chore(sdd): Delete spec ''`), announce success. iii. **If no:** Cancel. - * **If "Skip":** Leave track as is. + * **If "Skip":** Leave spec as is. """ diff --git a/packages/core/src/extensions/builtin/sdd/commands/spec/setup.toml b/packages/core/src/extensions/builtin/sdd/commands/spec/setup.toml index 6923d66622..c4d6510a91 100644 --- a/packages/core/src/extensions/builtin/sdd/commands/spec/setup.toml +++ b/packages/core/src/extensions/builtin/sdd/commands/spec/setup.toml @@ -15,7 +15,7 @@ PLAN MODE PROTOCOL: This setup process runs entirely within Plan Mode. While in > 1. **Project Discovery:** Analyze the current directory to determine if this is a new or existing project. > 2. **Product Definition:** Collaboratively define the product's vision, design guidelines, and technology stack. > 3. **Configuration:** Select appropriate code style guides and customize your development workflow. - > 4. **Track Generation:** Define the initial **track** (a high-level unit of work like a feature or bug fix) and automatically generate a detailed plan to start development. + > 4. **Spec Generation:** Define the initial **spec** (a high-level unit of work like a feature or bug fix) and automatically generate a detailed plan to start development. > > Let's get started!" @@ -24,25 +24,46 @@ PLAN MODE PROTOCOL: This setup process runs entirely within Plan Mode. While in ## 1.2 PROJECT AUDIT **PROTOCOL: Before starting the setup, determine the project's state by auditing existing artifacts.** -1. **Enter Plan Mode:** Call the `enter_plan_mode` tool with the reason: "Setting up SDD project". +1. **Legacy Migration Checks:** + a. **Directory Migration:** Check if a legacy `conductor/` directory exists in the root of the project. + - If `conductor/` exists and `.gemini/specs/` does NOT exist: + - Call the `ask_user` tool (do not repeat the question in the chat): + - **questions:** + - **header:** "Migrate Conductor" + - **type:** "yesno" + - **question:** "A legacy `conductor/` directory was detected. SDD now uses `.gemini/specs/` as its default directory. Would you like me to automatically migrate your existing `conductor/` directory to `.gemini/specs/`?" + - If the user answers "yes": + - Run `mkdir -p .gemini` + - Run `mv conductor/ .gemini/specs/` + - Announce: "Migration complete." + - If the user answers "no": + - Announce: "Setup aborted. Please manually rename the directory or configure your settings." + - **HALT** operation immediately. + b. **Terminology Migration (Tracks -> Specs):** Check if `.gemini/specs/tracks.md` or `.gemini/specs/tracks/` exists. + - If either exists, you MUST seamlessly migrate them to the new terminology: + - Rename the file `tracks.md` to `specs.md`. + - Rename the directory `tracks/` to `specs/`. + - Update any references to "tracks" to "specs" inside `.gemini/specs/index.md`. -2. **Announce Audit:** Inform the user that you are auditing the project for any existing SDD configuration. +2. **Enter Plan Mode:** Call the `enter_plan_mode` tool with the reason: "Setting up SDD project". -3. **Audit Artifacts:** Check the file system for the existence of the following files/directories in the `.gemini/specs/` directory: +3. **Announce Audit:** Inform the user that you are auditing the project for any existing SDD configuration. + +4. **Audit Artifacts:** Check the file system for the existence of the following files/directories in the `.gemini/specs/` directory: - `product.md` - `product-guidelines.md` - `tech-stack.md` - `code_styleguides/` - `workflow.md` - `index.md` - - `tracks/*/` (specifically `plan.md` and `index.md`) + - `specs/*/` (specifically `plan.md` and `index.md`) -4. **Determine Target Section:** Map the project's state to a target section using the priority table below (highest match wins). **DO NOT JUMP YET.** Keep this target in mind. +5. **Determine Target Section:** Map the project's state to a target section using the priority table below (highest match wins). **DO NOT JUMP YET.** Keep this target in mind. | Artifact Exists | Target Section | Announcement | | :--- | :--- | :--- | -| All files in `tracks//` (`spec`, `plan`, `metadata`, `index`) | **HALT** | "The project is already initialized. Use `/spec:create` or `/spec:implement`." | -| `index.md` (top-level) | **Section 3.0** | "Resuming setup: Scaffolding is complete. Next: generate the first track. (Note: If an incomplete track folder was detected, we will restart this step to ensure a clean, consistent state)." | +| All files in `specs//` (`spec`, `plan`, `metadata`, `index`) | **HALT** | "The project is already initialized. Use `/spec:create` or `/spec:implement`." | +| `index.md` (top-level) | **Section 3.0** | "Resuming setup: Scaffolding is complete. Next: generate the first spec. (Note: If an incomplete spec folder was detected, we will restart this step to ensure a clean, consistent state)." | | `workflow.md` | **Section 2.6** | "Resuming setup: Workflow is defined. Next: generate project index." | | `code_styleguides/` | **Section 2.5** | "Resuming setup: Guides/Tech Stack configured. Next: define project workflow." | | `tech-stack.md` | **Section 2.4** | "Resuming setup: Tech Stack defined. Next: select Code Styleguides." | @@ -50,7 +71,7 @@ PLAN MODE PROTOCOL: This setup process runs entirely within Plan Mode. While in | `product.md` | **Section 2.2** | "Resuming setup: Product Guide is complete. Next: create Product Guidelines." | | (None) | **Section 2.0** | (None) | -5. **Proceed to Section 2.0:** You MUST proceed to Section 2.0 to establish the Greenfield/Brownfield context before jumping to your target. +6. **Proceed to Section 2.0:** You MUST proceed to Section 2.0 to establish the Greenfield/Brownfield context before jumping to your target. --- @@ -387,22 +408,22 @@ PLAN MODE PROTOCOL: This setup process runs entirely within Plan Mode. While in - [Code Style Guides](./code_styleguides/) ## Management - - [Tracks Registry](./tracks.md) - - [Tracks Directory](./tracks/) + - [Spec Registry](./specs.md) + - [Spec Directory](./specs/) ``` - **Announce:** "Created `.gemini/specs/index.md` to serve as the project context index." 2. **Summarize Actions:** Present a summary of all actions taken during the initial setup, including: - The guide files that were copied. - The workflow file that was copied. -3. **Transition to initial plan and track generation:** Announce that the initial setup is complete and you will now proceed to define the first track for the project. +3. **Transition to initial plan and spec generation:** Announce that the initial setup is complete and you will now proceed to define the first spec for the project. --- -## 3.0 INITIAL PLAN AND TRACK GENERATION -**PROTOCOL: Interactively define project requirements, propose a single track, and then automatically create the corresponding track and its phased plan.** +## 3.0 INITIAL PLAN AND SPEC GENERATION +**PROTOCOL: Interactively define project requirements, propose a single spec, and then automatically create the corresponding spec and its phased plan.** -**Pre-Requisite (Cleanup):** If you are resuming this section because a previous setup was interrupted, check if the `.gemini/specs/tracks/` directory exists but is incomplete. If it exists, **delete** the entire `.gemini/specs/tracks/` directory before proceeding to ensure a clean slate for the new track generation. +**Pre-Requisite (Cleanup):** If you are resuming this section because a previous setup was interrupted, check if the `.gemini/specs/specs/` directory exists but is incomplete. If it exists, **delete** the entire `.gemini/specs/specs/` directory before proceeding to ensure a clean slate for the new spec generation. ### 3.1 Generate Product Requirements (Interactive)(For greenfield projects only) 1. **Transition to Requirements:** Announce that the initial project setup is complete. State that you will now begin defining the high-level product requirements by asking about topics like user stories and functional/non-functional requirements. @@ -443,64 +464,64 @@ PLAN MODE PROTOCOL: This setup process runs entirely within Plan Mode. While in - **options:** - Label: "Approve", Description: "The requirements look good, proceed to the next step." - Label: "Suggest changes", Description: "I want to modify the drafted content." -8. **Continue:** Once approved, retain these requirements in your context and immediately proceed to propose a track in the next section. +8. **Continue:** Once approved, retain these requirements in your context and immediately proceed to propose a spec in the next section. -### 3.2 Propose a Single Initial Track (Automated + Approval) -1. **State Your Goal:** Announce that you will now propose an initial track to get the project started. Briefly explain that a "track" is a high-level unit of work (like a feature or bug fix) used to organize the project. -2. **Generate Track Title:** Analyze the project context (`product.md`, `tech-stack.md`) and (for greenfield projects) the requirements gathered in the previous step. Generate a single track title that summarizes the entire initial track. +### 3.2 Propose a Single Initial Spec (Automated + Approval) +1. **State Your Goal:** Announce that you will now propose an initial spec to get the project started. Briefly explain that a "spec" is a high-level unit of work (like a feature or bug fix) used to organize the project. +2. **Generate Spec Title:** Analyze the project context (`product.md`, `tech-stack.md`) and (for greenfield projects) the requirements gathered in the previous step. Generate a single spec title that summarizes the entire initial spec. - **Greenfield:** Focus on the MVP core (e.g., "Build core tip calculator functionality"). - **Brownfield:** Focus on maintenance or targeted enhancements (e.g., "Implement user authentication flow"). 3. **Confirm Proposal:** Use the `ask_user` tool to validate the proposal: - **questions:** - - **header:** "Confirm Track" + - **header:** "Confirm Spec" - **type:** "choice" - **multiSelect:** false - - **question:** "To get the project started, I suggest the following track: ''. Do you want to proceed with this track?" + - **question:** "To get the project started, I suggest the following spec: ''. Do you want to proceed with this spec?" - **options:** - - Label: "Yes", Description: "Proceed with ''." - - Label: "Suggest changes", Description: "I want to define a different track." + - Label: "Yes", Description: "Proceed with ''." + - Label: "Suggest changes", Description: "I want to define a different spec." 4. **Action:** - - **If user chose "Yes":** Use the suggested '' as the track description. + - **If user chose "Yes":** Use the suggested '' as the spec description. - **If user chose "Suggest changes":** - Immediately call the `ask_user` tool again: - - **header:** "New Track" + - **header:** "New Spec" - **type:** "text" - - **question:** "Please enter the description for the initial track:" + - **question:** "Please enter the description for the initial spec:" - **placeholder:** "e.g., Setup CI/CD pipeline" - - Use the user's text response as the track description. - - Proceed to **Section 3.3** with the determined track description. + - Use the user's text response as the spec description. + - Proceed to **Section 3.3** with the determined spec description. -### 3.3 Convert the Initial Track into Artifacts (Automated) -1. **State Your Goal:** Once the track is approved, announce that you will now create the artifacts for this initial track. -2. **Initialize Tracks File:** Create the `.gemini/specs/tracks.md` file with the initial header and the first track: +### 3.3 Convert the Initial Spec into Artifacts (Automated) +1. **State Your Goal:** Once the spec is approved, announce that you will now create the artifacts for this initial spec. +2. **Initialize Specs File:** Create the `.gemini/specs/specs.md` file with the initial header and the first spec: ```markdown - # Project Tracks + # Project Specs - This file tracks all major tracks for the project. Each track has its own detailed plan in its respective folder. + This file tracks all major specs for the project. Each spec has its own detailed plan in its respective folder. --- - - [ ] **Track: ** - *Link: [.///](.///)* + - [ ] **Spec: ** + *Link: [.///](.///)* ``` - (Replace `` with the actual name of the tracks folder resolved via the protocol.) -3. **Generate Track Artifacts:** - a. **Define Track:** The approved title is the track description. - b. **Generate Track-Specific Spec & Plan:** - i. Automatically generate a detailed `spec.md` for this track. - ii. Automatically generate a `plan.md` for this track. + (Replace `` with the actual name of the specs folder resolved via the protocol.) +3. **Generate Spec Artifacts:** + a. **Define Spec:** The approved title is the spec description. + b. **Generate Specification & Plan:** + i. Automatically generate a detailed `spec.md` for this spec. + ii. Automatically generate a `plan.md` for this spec. - **CRITICAL:** The structure of the tasks must adhere to the principles outlined in the workflow file at `.gemini/specs/workflow.md`. For example, if the workflow specificies Test-Driven Development, each feature task must be broken down into a "Write Tests" sub-task followed by an "Implement Feature" sub-task. - **CRITICAL:** Include status markers `[ ]` for **EVERY** task and sub-task. The format must be: - Parent Task: `- [ ] Task: ...` - Sub-task: ` - [ ] ...` - **CRITICAL: Inject Phase Completion Tasks.** You MUST read the `.gemini/specs/workflow.md` file to determine if a "Phase Completion Verification and Checkpointing Protocol" is defined. If this protocol exists, then for each **Phase** that you generate in `plan.md`, you MUST append a final meta-task to that phase. The format for this meta-task is: `- [ ] Task: SDD - User Manual Verification '' (Protocol in workflow.md)`. You MUST replace `` with the actual name of the phase. - c. **Create Track Artifacts:** - i. **Generate and Store Track ID:** Create a unique Track ID from the track description using format `shortname_YYYYMMDD` and store it. You MUST use this exact same ID for all subsequent steps for this track. - ii. **Create Single Directory:** Resolve the **Tracks Directory** via the **Universal File Resolution Protocol** and create a single new directory: `//`. - iii. **Create `metadata.json`:** In the new directory, create a `metadata.json` file with the correct structure and content, using the stored Track ID. An example is: + c. **Create Spec Artifacts:** + i. **Generate and Store Spec ID:** Create a unique Spec ID from the spec description using format `shortname_YYYYMMDD` and store it. You MUST use this exact same ID for all subsequent steps for this spec. + ii. **Create Single Directory:** Resolve the **Spec Directory** by reading `.gemini/specs/index.md` and create a single new directory: `//`. + iii. **Create `metadata.json`:** In the new directory, create a `metadata.json` file with the correct structure and content, using the stored Spec ID. An example is: - ```json { - "track_id": "", + "spec_id": "", "type": "feature", // or "bug" "status": "new", // or in_progress, completed, cancelled "created_at": "YYYY-MM-DDTHH:MM:SSZ", @@ -512,23 +533,23 @@ PLAN MODE PROTOCOL: This setup process runs entirely within Plan Mode. While in iv. **Write Spec and Plan Files:** In the exact same directory, write the generated `spec.md` and `plan.md` files. v. **Write Index File:** In the exact same directory, write `index.md` with content: ```markdown - # Track Context + # Spec Context - [Specification](./spec.md) - [Implementation Plan](./plan.md) - [Metadata](./metadata.json) ``` - *(If you arrived here directly from the Audit because you are patching a missing index, write this file using the existing folder's track_id and then proceed to step d.)* + *(If you arrived here directly from the Audit because you are patching a missing index, write this file using the existing folder's spec_id and then proceed to step d.)* - d. **Exit Plan Mode:** Call the `exit_plan_mode` tool with the path: `//index.md`. + d. **Exit Plan Mode:** Call the `exit_plan_mode` tool with the path: `//index.md`. - e. **Announce Progress:** Announce that the track for "" has been created. + e. **Announce Progress:** Announce that the spec for "" has been created. ### 3.4 Final Announcement -1. **Announce Completion:** After the track has been created, announce that the project setup and initial track generation are complete. +1. **Announce Completion:** After the spec has been created, announce that the project setup and initial spec generation are complete. 1.5 **Ensure Artifact Visibility:** If a `.gitignore` file exists in the project root: - Check if it contains a rule that might ignore the `.gemini/specs/` directory (e.g., `.gemini/`). - To ensure these artifacts are always shared with the team, append `!.gemini/specs/` to the end of the `.gitignore` file if it is not already explicitly exempted. -2. **Save SDD Files:** Add and commit all files with the commit message `conductor(setup): Add conductor setup files`. +2. **Save SDD Files:** Add and commit all files with the commit message `sdd(setup): Add sdd setup files`. 3. **Next Steps:** Inform the user that they can now begin work by running `/spec:implement`. """ \ No newline at end of file diff --git a/packages/core/src/extensions/builtin/sdd/commands/spec/status.toml b/packages/core/src/extensions/builtin/sdd/commands/spec/status.toml index 0860ddd83c..e34240719d 100644 --- a/packages/core/src/extensions/builtin/sdd/commands/spec/status.toml +++ b/packages/core/src/extensions/builtin/sdd/commands/spec/status.toml @@ -1,7 +1,7 @@ description = "Displays the current progress of the project" prompt = """ ## 1.0 SYSTEM DIRECTIVE -You are an AI agent. Your primary function is to provide a status overview of the current tracks file. This involves reading the **Tracks Registry** file, parsing its content, and summarizing the progress of tasks. +You are an AI agent. Your primary function is to provide a status overview of the current specs file. This involves reading the **Spec Registry** file, parsing its content, and summarizing the progress of tasks. CRITICAL: You must validate the success of every tool call. If any tool call fails, you MUST halt the current operation immediately, announce the failure to the user, and await further instructions. @@ -11,8 +11,8 @@ CRITICAL: You must validate the success of every tool call. If any tool call fai ## 1.1 SETUP CHECK **PROTOCOL: Verify that the SDD environment is properly set up.** -1. **Verify Core Context:** Using the **Universal File Resolution Protocol**, resolve and verify the existence of: - - **Tracks Registry** +1. **Verify Core Context:** Read `.gemini/specs/index.md` to resolve the current file paths for the following artifacts. Verify they exist: + - **Spec Registry** - **Product Definition** - **Tech Stack** - **Workflow** @@ -28,11 +28,11 @@ CRITICAL: You must validate the success of every tool call. If any tool call fai **PROTOCOL: Follow this sequence to provide a status overview.** ### 2.1 Read Project Plan -1. **Locate and Read:** Read the content of the **Tracks Registry** (resolved via **Universal File Resolution Protocol**). -2. **Locate and Read Tracks:** - - Parse the **Tracks Registry** to identify all registered tracks and their paths. - * **Parsing Logic:** When reading the **Tracks Registry** to identify tracks, look for lines matching either the new standard format `- [ ] **Track:` or the legacy format `## [ ] Track:`. - - For each track, resolve and read its **Implementation Plan** (using **Universal File Resolution Protocol** via the track's index file). +1. **Locate and Read:** Read the content of the **Spec Registry** by resolving its path via `.gemini/specs/index.md`. +2. **Locate and Read Specs:** + - Parse the **Spec Registry** to identify all registered specs and their paths. + * **Parsing Logic:** When reading the **Spec Registry** to identify specs, look for lines matching either the new standard format `- [ ] **Spec:` or the legacy format `## [ ] Spec:`. + - For each spec, resolve and read its **Implementation Plan** by following the path in its respective index file. ### 2.2 Parse and Summarize Plan 1. **Parse Content:** diff --git a/packages/core/src/extensions/builtin/sdd/policies/sdd.toml b/packages/core/src/extensions/builtin/sdd/policies/sdd.toml index 1bf1bf9499..c1cb99083b 100644 --- a/packages/core/src/extensions/builtin/sdd/policies/sdd.toml +++ b/packages/core/src/extensions/builtin/sdd/policies/sdd.toml @@ -9,7 +9,7 @@ argsPattern = '"(?:file_path|path)":"\.gemini/specs/[^"]*"' # Allow tools used by SDD to set up specs dir [[rule]] toolName = "run_shell_command" -commandPrefix = ["git status", "git diff", "ls", "mkdir", "cp", "git init", "git add", "git commit"] +commandPrefix = ["git status", "git diff", "ls", "mkdir", "cp", "mv", "git init", "git add", "git commit"] decision = "ask_user" priority = 100 # prioritize over other extension policies modes = ["plan"] diff --git a/packages/core/src/extensions/builtin/sdd/templates/workflow.md b/packages/core/src/extensions/builtin/sdd/templates/workflow.md index 478e361ec7..c7c9d1b2b0 100644 --- a/packages/core/src/extensions/builtin/sdd/templates/workflow.md +++ b/packages/core/src/extensions/builtin/sdd/templates/workflow.md @@ -87,7 +87,7 @@ All tasks follow a strict lifecycle: 11. **Commit Plan Update:** - **Action:** Stage the modified `plan.md` file. - **Action:** Commit this change with a descriptive message (e.g., - `conductor(plan): Mark task 'Create user model' as complete`). + `sdd(plan): Mark task 'Create user model' as complete`). ### Phase Completion Verification and Checkpointing Protocol @@ -168,7 +168,7 @@ that also concludes a phase in `plan.md`. - Stage all changes. If no changes occurred in this step, proceed with an empty commit. - Perform the commit with a clear and concise message (e.g., - `conductor(checkpoint): Checkpoint end of Phase X`). + `sdd(checkpoint): Checkpoint end of Phase X`). 7. **Attach Auditable Verification Report using Git Notes:** - **Step 7.1: Draft Note Content:** Create a detailed verification report @@ -189,7 +189,7 @@ that also concludes a phase in `plan.md`. 9. **Commit Plan Update:** - **Action:** Stage the modified `plan.md` file. - **Action:** Commit this change with a descriptive message following the - format `conductor(plan): Mark phase '' as complete`. + format `sdd(plan): Mark phase '' as complete`. 10. **Announce Completion:** Inform the user that the phase is complete and the checkpoint has been created, with the detailed verification report attached