Install Script Deployment Workflow

Workflow ID: WF-INSTALL-001 Version: 1.0.0 Status: Active Effective Date: January 23, 2026 Owner: Hal Casteel, Founder/CEO/CTO, AZ1.AI INC

1. Overview

This workflow handles the complete lifecycle of CODITECT install script maintenance - from receiving user error reports to deploying validated fixes to Google Cloud Storage (GCS). It ensures:

Error Classification: Systematic categorization of user reports
Automated Analysis: Detection of hardcoded paths, schema issues, missing files
Fix Implementation: Following established patterns and ADR compliance
Safe Deployment: With health checks and automatic rollback
Audit Trail: Complete logging of all changes

2. Workflow Diagram

+-----------------------------------------------------------------------------+
|                    INSTALL SCRIPT DEPLOYMENT WORKFLOW                         |
+-----------------------------------------------------------------------------+
|                                                                               |
|   PHASE 1: ERROR INTAKE                                                       |
|   +-------------------+     +-------------------+     +-------------------+   |
|   |  Receive Error    | --> |  Parse Report     | --> |  Classify Issue   |   |
|   |  Report           |     |                   |     |  Type & Severity  |   |
|   +-------------------+     +-------------------+     +-------------------+   |
|                                       |                                       |
|                                       v                                       |
|   PHASE 2: ANALYSIS                                                           |
|   +-------------------+     +-------------------+     +-------------------+   |
|   |  Run Automated    | --> |  Identify Root    | --> |  Generate Fix     |   |
|   |  Checks           |     |  Cause            |     |  Recommendations  |   |
|   +-------------------+     +-------------------+     +-------------------+   |
|                                       |                                       |
|                                       v                                       |
|   PHASE 3: FIX IMPLEMENTATION                                                 |
|   +-------------------+     +-------------------+     +-------------------+   |
|   |  Apply Fixes      | --> |  Update Version   | --> |  Run Syntax       |   |
|   |  (Edit tool)      |     |  & Timestamp      |     |  Validation       |   |
|   +-------------------+     +-------------------+     +-------------------+   |
|                                       |                                       |
|                                       v                                       |
|   PHASE 4: CROSS-CHECK                                                        |
|   +-------------------+     +-------------------+     +-------------------+   |
|   |  Validate         | --> |  Validate         | --> |  Run Hook         |   |
|   |  ADR-057          |     |  ADR-103          |     |  Validator        |   |
|   +-------------------+     +-------------------+     +-------------------+   |
|                                       |                                       |
|                                       v                                       |
|   PHASE 5: GIT OPERATIONS                                                     |
|   +-------------------+     +-------------------+     +-------------------+   |
|   |  Stage Changes    | --> |  Generate Commit  | --> |  Create Commit    |   |
|   |                   |     |  Message          |     |  with Co-Author   |   |
|   +-------------------+     +-------------------+     +-------------------+   |
|                                       |                                       |
|                                       v                                       |
|   PHASE 6: GCS DEPLOYMENT                                                     |
|   +-------------------+     +-------------------+     +-------------------+   |
|   |  Backup Current   | --> |  Upload New       | --> |  Set Public       |   |
|   |  Version          |     |  Version          |     |  Permissions      |   |
|   +-------------------+     +-------------------+     +-------------------+   |
|                                       |                                       |
|                                       v                                       |
|   PHASE 7: POST-DEPLOY VALIDATION                                             |
|   +-------------------+     +-------------------+     +-------------------+   |
|   |  Download &       | --> |  Verify Version   | --> |  If Fail:         |   |
|   |  Verify           |     |  Match            |     |  Auto Rollback    |   |
|   +-------------------+     +-------------------+     +-------------------+   |
|                                                                               |
+-----------------------------------------------------------------------------+

3. Phase Details

Phase 1: Error Intake

Purpose: Receive and classify user error reports.

Step	Action	Details
1.1	Receive report	User submits error via issue, Slack, or direct message
1.2	Parse report	Extract error message, stack trace, context
1.3	Classify type	Match against known patterns
1.4	Assign severity	Critical/High/Medium/Low
1.5	Create task ID	F.X.Y.Z format for tracking

Issue Types:

Type	Patterns	Severity	Auto-Fixable
`hardcoded_path`	`/Users/`, `/home/`	High	Yes
`missing_file`	`FileNotFoundError`	High	No
`schema_mismatch`	`no such table`	Critical	Yes
`dependency_error`	`ImportError`	Medium	No
`permission_error`	`Permission denied`	Medium	No
`symlink_broken`	`broken symlink`	High	Yes
`hook_config_error`	`hook failed`	High	Yes

Output: Classified error report with task ID

Phase 2: Analysis

Purpose: Identify root cause through automated checks.

Step	Action	Command/Tool
2.1	Check hardcoded paths	`grep -n '/Users/\|/home/' scripts/CODITECT-CORE-INITIAL-SETUP.py`
2.2	Validate syntax	`python3 -m py_compile scripts/CODITECT-CORE-INITIAL-SETUP.py`
2.3	Check ADR-103 schema	Verify four databases referenced
2.4	Check ADR-057 steps	Verify 13 setup steps present
2.5	Run hook validator	`python3 hooks/validators/install-script-validator.py`

Analysis Script:

# Run comprehensive analysis
cd ~/.coditect

# 1. Hardcoded paths
echo "=== Hardcoded Path Check ==="
grep -n '/Users/\|/home/' scripts/CODITECT-CORE-INITIAL-SETUP.py || echo "No hardcoded paths found"

# 2. Syntax validation
echo "=== Syntax Check ==="
python3 -m py_compile scripts/CODITECT-CORE-INITIAL-SETUP.py && echo "Syntax OK"

# 3. ADR-118 four-tier database check
echo "=== ADR-118 Database Check ==="
for db in "platform.db" "org.db" "sessions.db" "project.db"; do
    grep -q "$db" scripts/CODITECT-CORE-INITIAL-SETUP.py && echo "$db: FOUND" || echo "$db: MISSING"
done

# 4. Version check
echo "=== Version Check ==="
grep 'SCRIPT_VERSION' scripts/CODITECT-CORE-INITIAL-SETUP.py

Output: Analysis report with identified issues and line numbers

Phase 3: Fix Implementation

Purpose: Apply fixes following established patterns.

Step	Action	Tool	Task ID Required
3.1	Apply fix	Edit	Yes: `F.X.Y.Z: Fix description`
3.2	Update version	Edit	Yes: `F.X.Y.Z: Bump version`
3.3	Update timestamp	Edit	Yes: `F.X.Y.Z: Update timestamp`
3.4	Validate syntax	Bash	Yes: `F.X.Y.Z: Syntax check`

Fix Patterns:

# Hardcoded Path Fix
# BEFORE:
LOG_DIR = "/Users/hal/PROJECTS/.coditect/logs"
# AFTER:
LOG_DIR = Path.home() / "PROJECTS" / ".coditect" / "logs"

# Schema Fix (ADR-118)
# Add missing database initialization
DATABASES = {
    'platform': CONTEXT_STORAGE / 'platform.db',    # Tier 1: Components
    'org': CONTEXT_STORAGE / 'org.db',              # Tier 2: Org knowledge
    'sessions': CONTEXT_STORAGE / 'sessions.db',    # Tier 3: Session data
    'project': CONTEXT_STORAGE / 'project.db',      # Tier 4: Project-specific
}

# Version Bump
SCRIPT_VERSION = "2.7.0"  # -> "2.7.1"
BUILD_TIMESTAMP = "2026-01-23T18:30:00Z"  # Update to current

Output: Fixed script with updated version

Phase 4: Cross-Check

Purpose: Validate fixes against architecture decisions.

Step	Validation	Command	Pass Criteria
4.1	ADR-057	Check symlink architecture	All paths correct
4.2	ADR-103	Check four-database schema	All 4 databases
4.3	ADR-074	Check hook configuration	Hooks properly configured
4.4	Hook validator	`python3 hooks/validators/install-script-validator.py`	Exit code 0

ADR Compliance Checklist:

## ADR-057 Compliance
- [ ] Protected location: ~/Library/Application Support/CODITECT/core/ (macOS)
- [ ] Protected location: ~/.local/share/coditect/core/ (Linux)
- [ ] Symlink: ~/PROJECTS/.coditect -> protected location
- [ ] Symlink: ~/PROJECTS/.claude -> .coditect
- [ ] Symlink: ~/.coditect -> protected location (backward compat)
- [ ] 13 setup steps implemented

## ADR-118 Compliance (Four-Tier Database)
- [ ] platform.db referenced (Tier 1: component metadata)
- [ ] org.db referenced (Tier 2: organization knowledge - CRITICAL)
- [ ] sessions.db referenced (Tier 3: session data)
- [ ] project.db referenced (Tier 4: project-specific)
- [ ] All in ~/PROJECTS/.coditect-data/context-storage/

Output: Compliance report (PASS/FAIL with details)

Phase 5: Git Operations

Purpose: Commit changes with proper conventions.

Step	Action	Command
5.1	Check status	`git status`
5.2	Stage changes	`git add scripts/CODITECT-CORE-INITIAL-SETUP.py`
5.3	Generate message	Follow conventional commit format
5.4	Create commit	`git commit -m "..."`

Commit Message Template:

fix(install-script): [Short description]

- [Bullet point of change 1]
- [Bullet point of change 2]
- Update version to X.Y.Z

Fixes: [USER-REPORT-YYYY-MM-DD or Issue #]
ADR-Compliance: ADR-057, ADR-103

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Example:

git commit -m "$(cat <<'EOF'
fix(install-script): Resolve hardcoded path in session logs migration

- Replace /Users/hal with Path.home() for cross-platform support
- Add projects.db initialization per ADR-103
- Update version to 2.7.1

Fixes: USER-REPORT-2026-01-23
ADR-Compliance: ADR-057, ADR-103

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
EOF
)"

Output: Git commit SHA

Phase 6: GCS Deployment

Purpose: Deploy to Google Cloud Storage with safety measures.

Step	Action	Command
6.1	Backup current	`gsutil cp gs://coditect-dist/coditect-install.py gs://coditect-dist/coditect-install.py.bak`
6.2	Upload new	`gsutil cp scripts/CODITECT-CORE-INITIAL-SETUP.py gs://coditect-dist/coditect-install.py`
6.3	Set permissions	`gsutil acl ch -u AllUsers:R gs://coditect-dist/coditect-install.py`
6.4	Verify upload	`gsutil stat gs://coditect-dist/coditect-install.py`

Deployment Script:

#!/bin/bash
set -e

SCRIPT="scripts/CODITECT-CORE-INITIAL-SETUP.py"
BUCKET="gs://coditect-dist"
FILE="coditect-install.py"

# Pre-flight check
python3 -m py_compile "$SCRIPT"

# Backup
echo "Backing up current version..."
gsutil cp "$BUCKET/$FILE" "$BUCKET/${FILE}.bak" 2>/dev/null || true

# Upload
echo "Uploading new version..."
gsutil cp "$SCRIPT" "$BUCKET/$FILE"

# Set public read
echo "Setting permissions..."
gsutil acl ch -u AllUsers:R "$BUCKET/$FILE"

echo "Deployment complete"
gsutil stat "$BUCKET/$FILE"

Output: GCS upload confirmation

Phase 7: Post-Deploy Validation

Purpose: Verify deployment success and rollback if needed.

Step	Action	Command
7.1	Download	`curl -sL https://storage.googleapis.com/coditect-dist/coditect-install.py -o /tmp/test.py`
7.2	Check size	Verify file not empty
7.3	Syntax check	`python3 -m py_compile /tmp/test.py`
7.4	Version check	Compare versions match
7.5	Rollback if fail	`gsutil cp gs://coditect-dist/coditect-install.py.bak gs://coditect-dist/coditect-install.py`

Health Check Script:

#!/bin/bash
URL="https://storage.googleapis.com/coditect-dist/coditect-install.py"
EXPECTED_VERSION=$(grep 'SCRIPT_VERSION' scripts/CODITECT-CORE-INITIAL-SETUP.py | grep -oE '[0-9]+\.[0-9]+\.[0-9]+')
TEMP_FILE="/tmp/health-check-install.py"

# Download
curl -sL "$URL" -o "$TEMP_FILE"

# Check not empty
if [ ! -s "$TEMP_FILE" ]; then
    echo "FAIL: Downloaded file is empty"
    exit 1
fi

# Syntax check
if ! python3 -m py_compile "$TEMP_FILE"; then
    echo "FAIL: Syntax error in deployed script"
    exit 1
fi

# Version check
DEPLOYED_VERSION=$(grep 'SCRIPT_VERSION' "$TEMP_FILE" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+')
if [ "$DEPLOYED_VERSION" != "$EXPECTED_VERSION" ]; then
    echo "FAIL: Version mismatch - expected $EXPECTED_VERSION, got $DEPLOYED_VERSION"
    exit 1
fi

echo "PASS: Health check successful - version $DEPLOYED_VERSION deployed"
rm -f "$TEMP_FILE"

Rollback Procedure:

# Automatic rollback on failure
if [ $HEALTH_CHECK_FAILED ]; then
    echo "Rolling back to previous version..."
    gsutil cp gs://coditect-dist/coditect-install.py.bak gs://coditect-dist/coditect-install.py
    gsutil acl ch -u AllUsers:R gs://coditect-dist/coditect-install.py
    echo "Rollback complete"
fi

Output: Deployment status (SUCCESS/ROLLED_BACK)

4. Error Handling

Phase Failure Matrix

Phase	Failure Mode	Recovery Action
1	Cannot classify	Manual review
2	Analysis timeout	Retry with simpler checks
3	Fix breaks syntax	Revert edit, manual fix
4	ADR compliance fail	Review ADRs, adjust fix
5	Git commit fails	Check for conflicts
6	GCS upload fails	Retry, check auth
7	Health check fails	Automatic rollback

Rollback Decision Tree

Health check result?
├── PASS → Done
└── FAIL
    ├── Backup exists?
    │   ├── YES → Rollback to .bak
    │   └── NO → Alert, manual intervention
    └── Log failure, notify team

5. Quick Reference

Commands

# Start workflow
/install-maintain "error report here"

# Analyze only
/install-maintain --analyze-only

# Deploy only (skip analysis)
/install-maintain --deploy-only

# Rollback
/install-maintain --rollback

Invocation

# Via agent
/agent install-script-maintainer "User reports: FileNotFoundError in session-retrospective.py"

# Via Task tool
Task(
    subagent_type="general-purpose",
    prompt="Use install-script-maintainer agent to fix install script issue: [description]"
)

6. Success Criteria

Metric	Target
Error classification accuracy	95%+
Fix success rate	90%+
Deployment success rate	99%+
Rollback success rate	100%
Time to deploy (minor fix)	< 30 minutes

Document	Purpose
install-script-maintainer	Agent reference
install-script-lifecycle	Patterns and practices
/install-maintain	Command reference
install-script-validator.py	Validation hook
ADR-057	Setup architecture
ADR-103	Database architecture

Workflow Owner: Hal Casteel, Founder/CEO/CTO, AZ1.AI INC Review Cycle: Monthly Next Review: February 23, 2026

1. Overview​

2. Workflow Diagram​

3. Phase Details​

Phase 1: Error Intake​

Phase 2: Analysis​

Phase 3: Fix Implementation​

Phase 4: Cross-Check​

Phase 5: Git Operations​

Phase 6: GCS Deployment​

Phase 7: Post-Deploy Validation​

4. Error Handling​

Phase Failure Matrix​

Rollback Decision Tree​

5. Quick Reference​

Commands​

Invocation​

6. Success Criteria​

7. Related Documents​