Refactor feature specification template for clarity and conciseness; add markdownlint configuration; implement ASCII and Mermaid diagram generators in Bash and PowerShell for architecture views.

Author: kanfil

.markdownlint.json

@@ -0,0 +1,11 @@
+{
+  "default": true,
+  "MD013": false,
+  "MD033": false,
+  "MD041": false,
+  "MD024": {
+    "siblings_only": true
+  },
+  "MD046": false,
+  "MD029": false
+}

docs/quickstart.md

@@ -15,8 +15,8 @@ This guide will help you get started with Spec-Driven Development using Agentic
 
 Specify supports two workflow modes that control development complexity, plus configurable framework opinions:
 
-- **`spec` mode (default)**: Full structured development with comprehensive requirements, research, and validation
-- **`build` mode**: Lightweight approach focused on quick implementation and exploration
+- **`spec` mode (default)**: Full structured development with comprehensive requirements, research, validation, and blocking review gates for team coordination
+- **`build` mode (GSD - Get Sh*t Done)**: High-velocity execution with atomic commits, non-blocking post-hoc review, and minimal documentation for rapid iteration
 
 **Framework Opinions** (configurable within each mode):
 
@@ -44,7 +44,11 @@ Specify supports two workflow modes that control development complexity, plus co
 /mode --info
 ```
 
-**Recommendation:** Start with `build` mode for exploration, switch to `spec` mode when features become complex or need thorough documentation.
+**Recommendation:**
+
+- Use **`build` mode** for: Individual development, rapid prototyping, quick wins, senior engineer autonomy
+- Use **`spec` mode** for: Team collaboration, complex systems, comprehensive documentation, rigorous validation
+- Switch between modes as needed: `/mode build` for fast iteration, `/mode spec` for thorough planning
 
 1. **Project Initialization (`/init`)**  
    **Action:** From the project root, run the Agentic SDLC Spec Kit `init` command (e.g., `specify init <project> --team-ai-directives https://github.com/your-org/team-ai-directives.git`) to configure local settings and clone the shared `team-ai-directives` modules.  

roadmap.md

@@ -202,15 +202,17 @@ check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
 if $PATHS_ONLY; then
     if $JSON_MODE; then
         # Minimal JSON paths payload (no validation performed)
-        printf '{"REPO_ROOT":"%s","BRANCH":"%s","FEATURE_DIR":"%s","FEATURE_SPEC":"%s","IMPL_PLAN":"%s","TASKS":"%s"}\n' \
-            "$REPO_ROOT" "$CURRENT_BRANCH" "$FEATURE_DIR" "$FEATURE_SPEC" "$IMPL_PLAN" "$TASKS"
+        printf '{"REPO_ROOT":"%s","BRANCH":"%s","FEATURE_DIR":"%s","FEATURE_SPEC":"%s","IMPL_PLAN":"%s","TASKS":"%s","CONSTITUTION":"%s","ARCHITECTURE":"%s"}\n' \
+            "$REPO_ROOT" "$CURRENT_BRANCH" "$FEATURE_DIR" "$FEATURE_SPEC" "$IMPL_PLAN" "$TASKS" "$CONSTITUTION" "$ARCHITECTURE"
     else
         echo "REPO_ROOT: $REPO_ROOT"
         echo "BRANCH: $CURRENT_BRANCH"
         echo "FEATURE_DIR: $FEATURE_DIR"
         echo "FEATURE_SPEC: $FEATURE_SPEC"
         echo "IMPL_PLAN: $IMPL_PLAN"
         echo "TASKS: $TASKS"
+        echo "CONSTITUTION: $CONSTITUTION"
+        echo "ARCHITECTURE: $ARCHITECTURE"
     fi
     exit 0
 fi
@@ -298,7 +300,29 @@ if $JSON_MODE; then
     SPEC_RISKS=$(extract_risks "$FEATURE_SPEC")
     PLAN_RISKS=$(extract_risks "$IMPL_PLAN")
     MODE_CONFIG=$(get_mode_config)
-    printf '{"FEATURE_DIR":"%s","AVAILABLE_DOCS":%s,"SPEC_RISKS":%s,"PLAN_RISKS":%s,"MODE_CONFIG":%s}\n' "$FEATURE_DIR" "$json_docs" "$SPEC_RISKS" "$PLAN_RISKS" "$MODE_CONFIG"
+    
+    # Check for constitution and architecture (optional governance documents)
+    CONSTITUTION_EXISTS="false"
+    ARCHITECTURE_EXISTS="false"
+    CONSTITUTION_RULES="[]"
+    ARCHITECTURE_VIEWS="{}"
+    ARCHITECTURE_DIAGRAMS="[]"
+    
+    if [[ -f "$CONSTITUTION" ]]; then
+        CONSTITUTION_EXISTS="true"
+        CONSTITUTION_RULES=$(extract_constitution_rules "$CONSTITUTION")
+    fi
+    
+    if [[ -f "$ARCHITECTURE" ]]; then
+        ARCHITECTURE_EXISTS="true"
+        ARCHITECTURE_VIEWS=$(extract_architecture_views "$ARCHITECTURE")
+        ARCHITECTURE_DIAGRAMS=$(extract_architecture_diagrams "$ARCHITECTURE")
+    fi
+    
+    printf '{"FEATURE_DIR":"%s","AVAILABLE_DOCS":%s,"SPEC_RISKS":%s,"PLAN_RISKS":%s,"MODE_CONFIG":%s,"CONSTITUTION":"%s","CONSTITUTION_EXISTS":%s,"CONSTITUTION_RULES":%s,"ARCHITECTURE":"%s","ARCHITECTURE_EXISTS":%s,"ARCHITECTURE_VIEWS":%s,"ARCHITECTURE_DIAGRAMS":%s}\n' \
+        "$FEATURE_DIR" "$json_docs" "$SPEC_RISKS" "$PLAN_RISKS" "$MODE_CONFIG" \
+        "$CONSTITUTION" "$CONSTITUTION_EXISTS" "$CONSTITUTION_RULES" \
+        "$ARCHITECTURE" "$ARCHITECTURE_EXISTS" "$ARCHITECTURE_VIEWS" "$ARCHITECTURE_DIAGRAMS"
 else
     # Text output
     echo "FEATURE_DIR:$FEATURE_DIR"
@@ -335,4 +359,10 @@ PY
 
     echo "SPEC_RISKS: $spec_risks_count"
     echo "PLAN_RISKS: $plan_risks_count"
+    
+    # Show governance document status
+    echo ""
+    echo "GOVERNANCE DOCUMENTS:"
+    check_file "$CONSTITUTION" "constitution.md (optional)"
+    check_file "$ARCHITECTURE" "architecture.md (optional)"
 fi

scripts/bash/ascii-generator.sh

@@ -37,6 +37,85 @@ get_current_mode() {
     fi
 }
 
+# Get a specific mode configuration value
+# Usage: get_mode_config "atomic_commits" → returns "true" or "false"
+# Usage: get_mode_config "skip_micro_review" → returns "true" or "false"
+get_mode_config() {
+    local key="$1"
+    local config_file
+    config_file=$(get_global_config_path)
+    
+    # Default to false if no config exists or jq not available
+    if [[ ! -f "$config_file" ]] || ! command -v jq >/dev/null 2>&1; then
+        echo "false"
+        return
+    fi
+    
+    # Get current mode
+    local mode
+    mode=$(get_current_mode)
+    
+    # Read mode-specific config value, default to false
+    local value
+    value=$(jq -r ".mode_defaults.${mode}.${key} // false" "$config_file" 2>/dev/null)
+    
+    echo "$value"
+}
+
+# Get architecture diagram format from global config (mermaid or ascii)
+# Defaults to "mermaid" if config doesn't exist or format is invalid
+get_architecture_diagram_format() {
+    local config_file
+    config_file=$(get_global_config_path)
+    
+    # Default to mermaid if no config exists or jq not available
+    if [[ ! -f "$config_file" ]] || ! command -v jq >/dev/null 2>&1; then
+        echo "mermaid"
+        return
+    fi
+    
+    # Read diagram format from config, default to mermaid
+    local format
+    format=$(jq -r '.architecture.diagram_format // "mermaid"' "$config_file" 2>/dev/null)
+    
+    # Validate format (only mermaid or ascii allowed)
+    if [[ "$format" == "mermaid" || "$format" == "ascii" ]]; then
+        echo "$format"
+    else
+        echo "mermaid"  # Fallback for invalid values
+    fi
+}
+
+# Validate Mermaid diagram syntax (lightweight regex validation)
+# Returns 0 if valid, 1 if invalid
+# Args: $1 - Mermaid code string
+validate_mermaid_syntax() {
+    local mermaid_code="$1"
+    
+    # Check if empty
+    if [[ -z "$mermaid_code" ]]; then
+        return 1
+    fi
+    
+    # Check for basic Mermaid diagram types
+    if ! echo "$mermaid_code" | grep -qE '^(graph|flowchart|sequenceDiagram|classDiagram|stateDiagram|erDiagram|gantt|pie|journey|gitGraph|mindmap|timeline)'; then
+        return 1
+    fi
+    
+    # Check for balanced brackets/parentheses (simplified)
+    local open_brackets=$(echo "$mermaid_code" | grep -o '\[' | wc -l)
+    local close_brackets=$(echo "$mermaid_code" | grep -o '\]' | wc -l)
+    local open_parens=$(echo "$mermaid_code" | grep -o '(' | wc -l)
+    local close_parens=$(echo "$mermaid_code" | grep -o ')' | wc -l)
+    
+    if [[ $open_brackets -ne $close_brackets ]] || [[ $open_parens -ne $close_parens ]]; then
+        return 1
+    fi
+    
+    # Basic syntax passed
+    return 0
+}
+
 load_team_directives_config() {
     local repo_root="$1"
 
@@ -195,6 +274,11 @@ get_feature_paths() {
     # Use prefix-based lookup to support multiple branches per spec
     local feature_dir=$(find_feature_dir_by_prefix "$repo_root" "$current_branch")
 
+    # Project-level governance documents
+    local memory_dir="$repo_root/.specify/memory"
+    local constitution_file="$memory_dir/constitution.md"
+    local architecture_file="$memory_dir/architecture.md"
+    
     cat <<EOF
 REPO_ROOT='$repo_root'
 CURRENT_BRANCH='$current_branch'
@@ -209,9 +293,179 @@ QUICKSTART='$feature_dir/quickstart.md'
 CONTEXT='$feature_dir/context.md'
 CONTRACTS_DIR='$feature_dir/contracts'
 TEAM_DIRECTIVES='${SPECIFY_TEAM_DIRECTIVES:-}'
+CONSTITUTION='$constitution_file'
+ARCHITECTURE='$architecture_file'
 EOF
 }
 
 check_file() { [[ -f "$1" ]] && echo "  ✓ $2" || echo "  ✗ $2"; }
 check_dir() { [[ -d "$1" && -n $(ls -A "$1" 2>/dev/null) ]] && echo "  ✓ $2" || echo "  ✗ $2"; }
 
+# Extract constitution principles and constraints
+# Returns JSON array of rules
+extract_constitution_rules() {
+    local constitution_file="$1"
+    
+    if [[ ! -f "$constitution_file" ]]; then
+        echo "[]"
+        return
+    fi
+    
+    python3 - "$constitution_file" <<'PY'
+import json
+import sys
+from pathlib import Path
+
+constitution_file = Path(sys.argv[1])
+rules = []
+
+try:
+    content = constitution_file.read_text()
+    
+    # Extract principles (lines starting with "- **Principle")
+    for line in content.split('\n'):
+        if line.strip().startswith('- **Principle') or line.strip().startswith('- **PRINCIPLE'):
+            rules.append({
+                'type': 'principle',
+                'text': line.strip()
+            })
+        elif line.strip().startswith('- **Constraint') or line.strip().startswith('- **CONSTRAINT'):
+            rules.append({
+                'type': 'constraint',
+                'text': line.strip()
+            })
+        elif line.strip().startswith('- **Pattern') or line.strip().startswith('- **PATTERN'):
+            rules.append({
+                'type': 'pattern',
+                'text': line.strip()
+            })
+    
+    print(json.dumps(rules, ensure_ascii=False))
+except Exception as e:
+    print('[]')
+PY
+}
+
+# Extract architecture viewpoints from architecture.md
+# Returns JSON with view names and component counts
+extract_architecture_views() {
+    local architecture_file="$1"
+    
+    if [[ ! -f "$architecture_file" ]]; then
+        echo "{}"
+        return
+    fi
+    
+    python3 - "$architecture_file" <<'PY'
+import json
+import sys
+from pathlib import Path
+import re
+
+architecture_file = Path(sys.argv[1])
+views = {}
+
+try:
+    content = architecture_file.read_text()
+    
+    # Track which views are present
+    view_patterns = {
+        'context': r'###\s+3\.1\s+Context\s+View',
+        'functional': r'###\s+3\.2\s+Functional\s+View',
+        'information': r'###\s+3\.3\s+Information\s+View',
+        'concurrency': r'###\s+3\.4\s+Concurrency\s+View',
+        'development': r'###\s+3\.5\s+Development\s+View',
+        'deployment': r'###\s+3\.6\s+Deployment\s+View',
+        'operational': r'###\s+3\.7\s+Operational\s+View'
+    }
+    
+    for view_name, pattern in view_patterns.items():
+        if re.search(pattern, content, re.IGNORECASE):
+            views[view_name] = {'present': True}
+        else:
+            views[view_name] = {'present': False}
+    
+    print(json.dumps(views, ensure_ascii=False))
+except Exception as e:
+    print('{}')
+PY
+}
+
+# Extract diagram blocks from architecture.md
+# Returns JSON array of diagrams with type and format
+extract_architecture_diagrams() {
+    local architecture_file="$1"
+    
+    if [[ ! -f "$architecture_file" ]]; then
+        echo "[]"
+        return
+    fi
+    
+    python3 - "$architecture_file" <<'PY'
+import json
+import sys
+from pathlib import Path
+import re
+
+architecture_file = Path(sys.argv[1])
+diagrams = []
+
+try:
+    content = architecture_file.read_text()
+    
+    # Find all code blocks (mermaid or text)
+    code_block_pattern = r'```(mermaid|text)\n(.*?)\n```'
+    
+    for match in re.finditer(code_block_pattern, content, re.DOTALL):
+        diagram_format = match.group(1)
+        diagram_content = match.group(2)
+        
+        # Try to determine which view this diagram belongs to by context
+        start_pos = match.start()
+        preceding_text = content[:start_pos]
+        
+        # Find the most recent view heading
+        view_match = None
+        for view_pattern in [
+            r'###\s+3\.1\s+Context\s+View',
+            r'###\s+3\.2\s+Functional\s+View',
+            r'###\s+3\.3\s+Information\s+View',
+            r'###\s+3\.4\s+Concurrency\s+View',
+            r'###\s+3\.5\s+Development\s+View',
+            r'###\s+3\.6\s+Deployment\s+View',
+            r'###\s+3\.7\s+Operational\s+View'
+        ]:
+            matches = list(re.finditer(view_pattern, preceding_text, re.IGNORECASE))
+            if matches:
+                view_match = matches[-1].group()
+                break
+        
+        view_name = 'unknown'
+        if view_match:
+            if 'Context' in view_match:
+                view_name = 'context'
+            elif 'Functional' in view_match:
+                view_name = 'functional'
+            elif 'Information' in view_match:
+                view_name = 'information'
+            elif 'Concurrency' in view_match:
+                view_name = 'concurrency'
+            elif 'Development' in view_match:
+                view_name = 'development'
+            elif 'Deployment' in view_match:
+                view_name = 'deployment'
+            elif 'Operational' in view_match:
+                view_name = 'operational'
+        
+        diagrams.append({
+            'view': view_name,
+            'format': diagram_format,
+            'line_count': len(diagram_content.split('\n'))
+        })
+    
+    print(json.dumps(diagrams, ensure_ascii=False))
+except Exception as e:
+    print('[]')
+PY
+}
+