Merge pull request #258 from buildermethods/2.1.1

Version 2.1.1

Author: CasJam

CHANGELOG.md

@@ -3,6 +3,14 @@
 Get notified of major releases by subscribing here:
 https://buildermethods.com/agent-os
 
+## [2.1.1] - 2025-10-29
+
+- Replaced references to 'spec-researcher' (depreciated agent name) with 'spec-shaper'.
+- Clarified --dry-run output to user to reassure we're in dry-run mode
+- Tightened up template and istructions for writing spec.md, aiming to keep it shorter, easier to scan, and covering only the essentials.
+- Tweaked create-task-list workflow for consistency.
+- When planning product roadmap, removed instruction to limit it to 12 items.
+
 ## [2.1.0] - 2025-10-21
 
 Version 2.1 implemented a round of significant changes to how things work in Agent OS.  Here is a summary of what's new in version 2.1.0:

config.yml

@@ -1,4 +1,4 @@
-version: 2.1.0
+version: 2.1.1
 base_install: true
 
 

profiles/default/commands/shape-spec/multi-agent/shape-spec.md

@@ -16,26 +16,26 @@ Follow each of these phases and their individual workflows IN SEQUENCE:
 
 ### PHASE 1: Initialize Spec
 
-Use the **spec-initializer** subagent to initialize a new spec.
+Use the **spec-shaper** subagent to initialize a new spec.
 
 IF the user has provided a description, provide that to the spec-initializer.
 
 The spec-initializer will provide the path to the dated spec folder (YYYY-MM-DD-spec-name) they've created.
 
 ### PHASE 2: Research Requirements
 
-After spec-initializer completes, immediately use the **spec-researcher** subagent:
+After spec-initializer completes, immediately use the **spec-shaper** subagent:
 
-Provide the spec-researcher with:
+Provide the spec-shaper with:
 - The spec folder path from spec-initializer
 
-The spec-researcher will give you several separate responses that you MUST show to the user. These include:
+The spec-shaper will give you several separate responses that you MUST show to the user. These include:
 1. Numbered clarifying questions along with a request for visual assets (show these to user, wait for user's response)
 2. Follow-up questions if needed (based on user's answers and provided visuals)
 
 **IMPORTANT**:
 - Display these questions to the user and wait for their response
-- The spec-researcher may ask you to relay follow-up questions that you must present to user
+- The spec-shaper may ask you to relay follow-up questions that you must present to user
 
 ### PHASE 3: Inform the user
 

profiles/default/workflows/implementation/create-tasks-list.md

@@ -4,14 +4,14 @@
 
 1. **Analyze spec and requirements**: Read and analyze the spec.md and/or requirements.md to inform the tasks list you will create.
 2. **Plan task execution order**: Break the requirements into a list of tasks in an order that takes their dependencies into account.
-3. **Group tasks by specialization**: Group tasks that should be handled by the same specialist together.
+3. **Group tasks by specialization**: Group tasks that require the same skill or stack specialization together (backend, api, ui design, etc.)
 4. **Create Tasks list**: Create the markdown tasks list broken into groups with sub-tasks.
 
 ## Workflow
 
 ### Step 1: Analyze Spec & Requirements
 
-Read each of these files (if available) and analyze them to understand the requirements for this feature implementation:
+Read each of these files (whichever are available) and analyze them to understand the requirements for this feature implementation:
 - `agent-os/specs/[this-spec]/spec.md`
 - `agent-os/specs/[this-spec]/planning/requirements.md`
 
@@ -188,7 +188,7 @@ Recommended implementation sequence:
 ## Important Constraints
 
 - **Create tasks that are specific and verifiable**
-- **Group related tasks** for efficient specialists implementer assignment. For example, group back-end engineering tasks together and front-end UI tasks together.
+- **Group related tasks:** For example, group back-end engineering tasks together and front-end UI tasks together.
 - **Limit test writing during development**:
   - Each task group (1-3) should write 2-8 focused tests maximum
   - Tests should cover only critical behaviors, not exhaustive coverage

profiles/default/workflows/planning/create-product-roadmap.md

@@ -6,7 +6,7 @@ Do not include any tasks for initializing a new codebase or bootstrapping a new
 
 1. **Review the Mission** - Read `agent-os/product/mission.md` to understand the product's goals, target users, and success criteria.
 
-2. **Identify Features** - Based on the mission, determine 4–12 concrete features needed to achieve the product vision.
+2. **Identify Features** - Based on the mission, determine the list of concrete features needed to achieve the product vision.
 
 3. **Strategic Ordering** - Order features based on:
    - Technical dependencies (foundational features first)
@@ -29,7 +29,6 @@ Do not include any tasks for initializing a new codebase or bootstrapping a new
 8. [ ] [FEATURE_NAME] — [1-2 SENTENCE DESCRIPTION OF COMPLETE, TESTABLE FEATURE] `[EFFORT]`
 
 > Notes
-> - Include 4–12 items total
 > - Order items by technical dependencies and product architecture
 > - Each item should represent an end-to-end (frontend + backend) functional and testable feature
 ```

profiles/default/workflows/specification/write-spec.md

@@ -21,7 +21,7 @@ ls -la agent-os/specs/[current-spec]/planning/visuals/ 2>/dev/null | grep -v "^t
 
 Parse and analyze:
 - User's feature description and goals
-- Requirements gathered by spec-researcher
+- Requirements gathered by spec-shaper
 - Visual mockups or screenshots (if present)
 - Any constraints or out-of-scope items mentioned
 
@@ -62,41 +62,32 @@ Follow this structure exactly when creating the content of `spec.md`:
 
 ## User Stories
 - As a [user type], I want to [action] so that [benefit]
-- [Additional stories based on requirements]
+- [repeat for up to 2 max additional user stories]
 
-## Core Requirements
-- [User-facing capability]
-- [What users can do]
-- [Key features to implement]
+## Specific Requirements
+
+**Specific requirement name**
+- [Up to 8 CONCISE sub-bullet points to clarify specific sub-requirements, design or architectual decisions that go into this requirement, or the technical approach to take when implementing this requirement]
+
+[repeat for up to a max of 10 specific requirements]
 
 ## Visual Design
 [If mockups provided]
-- Mockup reference: `planning/visuals/[filename]`
-- Key UI elements to implement
-- Responsive breakpoints required
 
-## Reusable Components
-### Existing Code to Leverage
-- Components: [List found components]
-- Services: [List found services]
-- Patterns: [Similar features to model after]
+**`planning/visuals/[filename]`**
+- [up to 8 CONCISE bullets describing specific UI elements found in this visual to address when building]
+
+[repeat for each file in the `planning/visuals` folder]
+
+## Existing Code to Leverage
 
-### New Components Required
-- [Component that doesn't exist yet]
-- [Why it can't reuse existing code]
+**Code, component, or existing logic found**
+- [up to 5 bullets that describe what this existing code does and how it should be re-used or replicated when building this spec]
 
-## Technical Approach
-- [Briefly describe specific technical notes to ensure alignment with requirements.md]
+[repeat for up to 5 existing code areas]
 
 ## Out of Scope
-- [Features not being built now]
-- [Future enhancements]
-- [Items explicitly excluded]
-
-## Success Criteria
-- [Measurable outcome]
-- [Performance metric]
-- [User experience goal]
+- [up to 10 concise descriptions of specific features that are out of scope and MUST NOT be built in this spec]
 ```
 
 ## Important Constraints
@@ -105,4 +96,4 @@ Follow this structure exactly when creating the content of `spec.md`:
 2. **Reference visual assets** when available
 3. **Do NOT write actual code** in the spec
 4. **Keep each section short**, with clear, direct, skimmable specifications
-5. **Document WHY new code is needed** if can't reuse existing
+5. **Do NOT deviate from the template above** and do not add additional sections

scripts/project-update.sh

@@ -678,14 +678,24 @@ prompt_update_confirmation() {
         echo ""
         print_color "$PURPLE" "=== Version/Configuration Update Required ==="
         echo ""
+        if [[ "$DRY_RUN" == "true" ]]; then
+            print_warning "Dry run simulation"
+        fi
         echo ""
         print_status "Your project's Agent OS version and/or configuration is different than the version you're trying to install."
     else
         echo ""
         print_color "$PURPLE" "=== Confirm Update ==="
         echo ""
+        if [[ "$DRY_RUN" == "true" ]]; then
+            print_warning "Dry run simulation"
+        fi
         echo ""
-        print_status "Confirm you'd like to proceed with an update."
+        if [[ "$DRY_RUN" == "true" ]]; then
+            print_status "Confirm you'd like to proceed with a DRY RUN update simulation."
+        else
+            print_status "Confirm you'd like to proceed with an update."
+        fi
     fi
     echo ""
 
@@ -722,14 +732,22 @@ prompt_update_confirmation() {
     echo ""
 
     # Show what will happen
-    print_status "Here's what will happen if you proceed:"
+    if [[ "$DRY_RUN" == "true" ]]; then
+        print_status "Here's what WOULD happen if this were a real update (but it's a DRY RUN):"
+    else
+        print_status "Here's what will happen if you proceed:"
+    fi
     echo ""
     echo -e "${GREEN}✔ These will remain intact:${NC}"
     echo ""
     echo "  - agent-os/specs/*"
     echo "  - agent-os/product/*"
     echo ""
-    echo -e "${YELLOW}⚠️  These will be deleted and re-installed to match the new version and configurations:${NC}"
+    if [[ "$DRY_RUN" == "true" ]]; then
+        echo -e "${YELLOW}⚠️  These WOULD BE deleted and re-installed to match the new version and configurations if this were a real update (but it's a DRY RUN):${NC}"
+    else
+        echo -e "${YELLOW}⚠️  These will be deleted and re-installed to match the new version and configurations:${NC}"
+    fi
     echo ""
     echo "  - agent-os/config.yml"
     echo "  - agent-os/standards/"
@@ -759,7 +777,7 @@ prompt_update_confirmation() {
 # Perform cleanup before update - delete everything except specs/ and product/
 perform_update_cleanup() {
     if [[ "$DRY_RUN" == "true" ]]; then
-        print_status "Dry run: Would prepare for update..."
+        print_warning "Dry run: Would prepare for update..."
         echo ""
     else
         print_status "Preparing for update..."