docs(architect): Add user prompt/context examples to documentation

- Update README.md with context usage examples for all architect actions
- Add 'Pro Tip' section explaining benefit of providing context
- Update architect.md template with example prompts and usage guidance
- Enhance setup-architecture.sh help text with concrete examples
- Enhance setup-architecture.ps1 help text with PowerShell examples
- Update Phase 0 instructions to conditionally use provided context

Users can now clearly see they can provide system descriptions directly:
  /architect init "B2B SaaS for supply chain management"
  /architect map "Django monolith with PostgreSQL and React"

This improves discoverability of existing capability and reduces
need for interactive question-answering when context is known upfront.

Author: kanfil

README.md

@@ -312,15 +312,27 @@ The toolkit includes comprehensive architecture documentation support that works
 # Initialize architecture documentation (greenfield projects)
 /speckit.architect init
 
+# Or provide context directly for better results
+/speckit.architect init "B2B SaaS platform for real-time supply chain management"
+
 # Map existing codebase architecture (brownfield projects)
 /speckit.architect map
 
+# Add system description to guide the mapping
+/speckit.architect map "Django monolith with PostgreSQL, React frontend, deployed on AWS ECS"
+
 # Review architecture against constitution
 /speckit.architect review
 
+# Specify review focus areas
+/speckit.architect review "Validate security compliance and data privacy requirements"
+
 # Update architecture as system evolves
 /speckit.architect update
 
+# Describe what changed for targeted analysis
+/speckit.architect update "Migrated to microservices, added event sourcing and message queue"
+
 # Then proceed with normal workflow
 /speckit.specify "Feature within this architecture"
 ```
@@ -334,6 +346,13 @@ The toolkit includes comprehensive architecture documentation support that works
 | `update` | Update architecture based on codebase/spec changes with impact analysis |
 | `review` | Validate architecture against constitution and perspectives |
 
+**Pro Tip**: Add context/prompts directly after the action for better results. For example:
+
+- `init "Enterprise healthcare SaaS for compliance tracking"` - AI understands system scope from the start
+- `map "Node.js microservices on Kubernetes"` - Combines codebase scan with your description
+- `update "Added authentication service and event sourcing"` - Focuses analysis on specific changes
+- `review "Focus on security and performance"` - Prioritizes specific architectural concerns
+
 #### Rozanski & Woods Viewpoints
 
 The `/speckit.architect` command generates documentation covering:

scripts/bash/setup-architecture.sh

@@ -16,7 +16,7 @@ for arg in "$@"; do
             ACTION="$arg"
             ;;
         --help|-h)
-            echo "Usage: $0 [action] [--json]"
+            echo "Usage: $0 [action] [context] [--json]"
             echo ""
             echo "Actions:"
             echo "  init     Initialize new memory/architecture.md from template"
@@ -27,6 +27,15 @@ for arg in "$@"; do
             echo "Options:"
             echo "  --json   Output results in JSON format"
             echo "  --help   Show this help message"
+            echo ""
+            echo "Examples:"
+            echo "  $0 init \"B2B SaaS for supply chain management\""
+            echo "  $0 map \"Django monolith with PostgreSQL and React\""
+            echo "  $0 update \"Added microservices and event sourcing\""
+            echo "  $0 review \"Focus on security and performance\""
+            echo ""
+            echo "Pro Tip: Add context/description after the action for better results."
+            echo "The AI will use your input to understand system scope and constraints."
             exit 0
             ;;
         *)

scripts/powershell/setup-architecture.ps1

@@ -11,7 +11,7 @@ param(
 $ErrorActionPreference = 'Stop'
 
 if ($Help) {
-    Write-Output "Usage: ./setup-architecture.ps1 [action] [-Json] [-Help]"
+    Write-Output "Usage: ./setup-architecture.ps1 [action] [context] [-Json] [-Help]"
     Write-Output ""
     Write-Output "Actions:"
     Write-Output "  init     Initialize new memory/architecture.md from template"
@@ -22,6 +22,15 @@ if ($Help) {
     Write-Output "Options:"
     Write-Output "  -Json    Output results in JSON format"
     Write-Output "  -Help    Show this help message"
+    Write-Output ""
+    Write-Output "Examples:"
+    Write-Output "  ./setup-architecture.ps1 init `"B2B SaaS for supply chain management`""
+    Write-Output "  ./setup-architecture.ps1 map `"Django monolith with PostgreSQL and React`""
+    Write-Output "  ./setup-architecture.ps1 update `"Added microservices and event sourcing`""
+    Write-Output "  ./setup-architecture.ps1 review `"Focus on security and performance`""
+    Write-Output ""
+    Write-Output "Pro Tip: Add context/description after the action for better results."
+    Write-Output "The AI will use your input to understand system scope and constraints."
     exit 0
 }
 

templates/commands/architect.md

@@ -25,6 +25,15 @@ $ARGUMENTS
 
 You **MUST** consider the user input before proceeding (if not empty).
 
+**Examples of User Input**:
+
+- `init "B2B SaaS platform for supply chain management"`
+- `map "Django monolith with PostgreSQL, React frontend, AWS deployment"`
+- `update "Migrated to microservices, added event sourcing and Kafka"`
+- `review "Focus on security compliance and performance scalability"`
+
+When users provide context like this, use it to inform your architecture work. This context helps you understand system scope, constraints, and focus areas without needing to ask basic questions.
+
 ## Outline
 
 The text the user typed after `/speckit.architect` in the triggering message **is** the architecture action (init/map/update/review) and context. Assume you always have it available in this conversation even if `{ARGS}` appears literally below. Do not ask the user to repeat it unless they provided an empty command.
@@ -106,6 +115,10 @@ The command supports four actions:
 
 **Objective**: Establish stakeholders, concerns, and system scope
 
+**If user provided context in {ARGS}**: Parse it for system description, scope, and constraints. Use this to skip basic questions and focus on clarifying details.
+
+**If user provided minimal/no context**: Follow full discovery process below.
+
 1. **Identify Stakeholders**:
    - Read `memory/constitution.md` if it exists
    - Prompt user to identify key stakeholders (Product Owner, Operations, Security, End Users)