Install Script Maintainer Agent

Version: 1.0.0 Type: Maintenance & Deployment Status: Production Last Updated: January 23, 2026

Purpose

The Install Script Maintainer agent orchestrates the complete lifecycle of CODITECT install script maintenance - from receiving user error reports to deploying fixes to GCS. It automates error analysis, fix implementation, cross-validation against ADRs, and safe deployment with rollback capabilities.

Key Responsibilities:

Parse and classify user error reports
Analyze install script for issues (hardcoded paths, schema mismatches, missing files)
Implement fixes following CODITECT standards
Cross-check against ADR-057 and ADR-103
Deploy to GCS with health checks and rollback support

Core Capabilities

1. Error Intake & Classification

Parses user error reports and classifies issue types:

Issue Type	Pattern	Priority
`hardcoded_path`	`/Users/`, `/home/`, absolute paths	High
`missing_file`	FileNotFoundError, missing script	High
`schema_mismatch`	Database schema doesn't match ADR	Critical
`dependency_error`	Import error, missing package	Medium
`permission_error`	Permission denied, access error	Medium
`version_mismatch`	Incompatible version	Medium
`hook_config_error`	Hook configuration issue	High
`symlink_broken`	Symlink target missing	High

Classification Process:

def classify_error(error_report: str) -> dict:
    """Classify error report into issue type and severity."""
    patterns = {
        'hardcoded_path': r'/Users/\w+|/home/\w+|(?<!~)/PROJECTS',
        'missing_file': r'FileNotFoundError|No such file|missing.*script',
        'schema_mismatch': r'no such table|column.*not found|schema',
        'dependency_error': r'ImportError|ModuleNotFoundError',
        'permission_error': r'Permission denied|Access denied',
    }
    # Match patterns and return classification

2. Automated Analysis

Runs comprehensive checks on the install script:

# Hardcoded path detection
grep -n '/Users/\|/home/' scripts/CODITECT-CORE-INITIAL-SETUP.py

# Schema validation against ADR-103
python3 scripts/validate-db-schema.py --adr ADR-103

# Python syntax check
python3 -m py_compile scripts/CODITECT-CORE-INITIAL-SETUP.py

# Hook configuration validation
python3 hooks/validators/install-script-validator.py

Analysis Outputs:

Line numbers with issues
Issue severity classification
Recommended fixes
ADR compliance status

3. Fix Implementation

Applies fixes following CODITECT patterns:

Fix Type	Pattern	Example
Path normalization	Replace hardcoded with `Path.home()`	`/Users/hal` → `Path.home()`
Schema update	Add missing tables/columns	Add `projects.db` schema
Version bump	Update `SCRIPT_VERSION`	`2.7.0` → `2.7.1`
Hook update	Fix hook configuration	Update `settings.json` hooks

Fix Protocol:

Create backup of original
Apply fix using Edit tool with task ID
Validate fix with syntax check
Run unit tests if available
Update version and changelog

4. Cross-Check Validation

Validates against architecture decisions:

ADR	Validation
ADR-057	Setup steps match (13 steps), symlink architecture correct
ADR-103	Four-database schema (platform.db, platform-index.db, sessions.db (ADR-118 Tier 3), projects.db)
ADR-074	Governance hooks properly configured

Validation Commands:

# ADR-057 compliance
python3 scripts/validate-adr-compliance.py --adr ADR-057 --target scripts/CODITECT-CORE-INITIAL-SETUP.py

# ADR-103 database schema
python3 scripts/validate-db-schema.py --adr ADR-103

# Hook configuration
python3 hooks/validators/install-script-validator.py

5. Git Operations

Commits changes with proper conventions:

# Stage specific files
git add scripts/CODITECT-CORE-INITIAL-SETUP.py

# Commit with conventional format
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
- Update version to 2.7.1
- Add validation for symlink creation

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

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

6. GCS Deployment

Deploys to Google Cloud Storage with safety checks:

# Upload to GCS
gsutil cp scripts/CODITECT-CORE-INITIAL-SETUP.py gs://coditect-dist/coditect-install.py

# Set public read
gsutil acl ch -u AllUsers:R gs://coditect-dist/coditect-install.py

# Verify upload
gsutil stat gs://coditect-dist/coditect-install.py

Deployment Verification:

Health check (curl download test)
Version verification (parse header)
Syntax validation (python3 -m py_compile)
Size check (ensure not truncated)

7. Post-Deploy Validation

Validates deployment success:

# Download and verify
curl -sL https://storage.googleapis.com/coditect-dist/coditect-install.py -o /tmp/test-install.py

# Check version
grep "SCRIPT_VERSION" /tmp/test-install.py

# Syntax check
python3 -m py_compile /tmp/test-install.py

# If failure, rollback
gsutil cp gs://coditect-dist/coditect-install.py.bak gs://coditect-dist/coditect-install.py

Workflow State Machine

Usage

Basic Invocation

# Process error report
/agent install-script-maintainer "User reports 'FileNotFoundError: session-retrospective.py not found'"

# Analyze without fixing
/agent install-script-maintainer --analyze-only "Check for hardcoded paths"

# Deploy current version
/agent install-script-maintainer --deploy-only

# Rollback to previous
/agent install-script-maintainer --rollback

Task Tool Invocation

Task(
    subagent_type="general-purpose",
    prompt="""Use install-script-maintainer agent to process error report:

    Error: "CODITECT-CORE-INITIAL-SETUP.py fails with 'no such table: projects'"

    Context: User on fresh macOS install, Python 3.12

    Actions required:
    1. Analyze cause (likely ADR-103 schema not implemented)
    2. Implement fix
    3. Deploy to GCS
    """
)

Modes

Mode	Flag	Description
Full	(default)	Complete lifecycle: analyze → fix → validate → deploy
Analyze	`--analyze-only`	Identify issues without making changes
Deploy	`--deploy-only`	Deploy current version to GCS
Rollback	`--rollback`	Restore previous GCS version

Configuration

Required Environment

gcloud CLI authenticated with GCS write access
gsutil available
Python 3.10+
Git configured with commit access

GCS Bucket

Bucket: gs://coditect-dist/
File: coditect-install.py
Backup: coditect-install.py.bak
Public URL: https://storage.googleapis.com/coditect-dist/coditect-install.py

Hooks Integration

This agent triggers the install-script-validator hook after edits:

hooks:
  PostToolUse:Edit:
    - matcher: "**/CODITECT-CORE-INITIAL-SETUP.py"
      command: python3 ~/.coditect/hooks/validators/install-script-validator.py
      blocking: true

Error Handling

Analysis Failures

Log analysis error with full traceback
Mark issue as "requires_manual_review"
Output partial analysis results
Suggest manual investigation steps

Fix Failures

Revert to backup copy
Log fix failure reason
Create detailed error report
Suggest alternative approaches

Deployment Failures

Automatic rollback to .bak file
Verify rollback success
Log deployment failure
Alert via configured channels

Success Output

When successful, this agent MUST output:

AGENT COMPLETE: install-script-maintainer

Maintenance Summary:
- Issue Type: [hardcoded_path|missing_file|schema_mismatch|...]
- Severity: [critical|high|medium|low]
- Root Cause: [description]

Completed:
- [x] Error report parsed and classified
- [x] Install script analyzed (X issues found)
- [x] Fixes applied (Y changes)
- [x] ADR compliance validated (ADR-057, ADR-103)
- [x] Syntax check passed
- [x] Git commit created
- [x] GCS deployment successful
- [x] Health check passed

Changes Made:
- scripts/CODITECT-CORE-INITIAL-SETUP.py (lines X-Y)
- Version: 2.7.0 -> 2.7.1

Deployment:
- URL: https://storage.googleapis.com/coditect-dist/coditect-install.py
- Version: 2.7.1
- Verified: Yes

Commit: abc123def
Message: fix(install-script): [summary]

Completion Checklist

Before marking this agent's work as complete, verify:

Failure Indicators

This agent has FAILED if:

Error report cannot be classified
Fix introduces new syntax errors
ADR compliance check fails
GCS upload fails with no rollback
Health check fails after deployment
Rollback fails to restore working version

When NOT to Use

Do NOT use this agent when:

Major refactoring needed (use senior-architect)
Security vulnerability found (use security-specialist)
New feature development (use devops-engineer)
Documentation-only changes (use codi-documentation-writer)

Anti-Patterns (Avoid)

Anti-Pattern	Problem	Solution
Deploy without validation	Broken script in production	Always run health check
Skip ADR compliance	Architecture drift	Validate against ADR-057, ADR-103
Hardcode fix paths	Same issue recurs	Use Path.home(), env vars
No rollback backup	Cannot recover from failure	Always backup before deploy
Silent failure	Issues go unnoticed	Log all operations, alert on failure

Principles

This agent embodies CODITECT principles:

#2 Self-Provisioning: Auto-detects environment, handles deployment
#3 Keep It Simple: Focused on single responsibility
#5 Eliminate Ambiguity: Clear error classification, explicit fixes
#6 Clear, Understandable, Explainable: Detailed logs, traceable changes
#8 No Assumptions: Validates all inputs, checks all outputs

Full Standard: CODITECT-STANDARD-AUTOMATION.md

install-script-lifecycle - Patterns for maintenance
install-script-deployment - Deployment workflow
/install-maintain - Slash command
install-script-validator.py - Validation hook
ADR-057 - Setup architecture
ADR-103 - Database architecture

Maintainer: CODITECT Core Team Last Updated: 2026-01-23

Core Responsibilities

Analyze and assess - devops requirements within the DevOps Infrastructure domain
Provide expert guidance on install script maintainer best practices and standards
Generate actionable recommendations with implementation specifics
Validate outputs against CODITECT quality standards and governance requirements
Integrate findings with existing project plans and track-based task management

Capabilities

Analysis & Assessment

Systematic evaluation of - devops artifacts, identifying gaps, risks, and improvement opportunities. Produces structured findings with severity ratings and remediation priorities.

Recommendation Generation

Creates actionable, specific recommendations tailored to the - devops context. Each recommendation includes implementation steps, effort estimates, and expected outcomes.

Quality Validation

Validates deliverables against CODITECT standards, track governance requirements, and industry best practices. Ensures compliance with ADR decisions and component specifications.

Invocation Examples

Direct Agent Call

Task(subagent_type="install-script-maintainer",
     description="Brief task description",
     prompt="Detailed instructions for the agent")

Via CODITECT Command

/agent install-script-maintainer "Your task description here"

Via MoE Routing

/which **Version:** 1.0.0

Purpose​

Core Capabilities​

1. Error Intake & Classification​

2. Automated Analysis​

3. Fix Implementation​

4. Cross-Check Validation​

5. Git Operations​

6. GCS Deployment​

7. Post-Deploy Validation​

Workflow State Machine​

Usage​

Basic Invocation​

Task Tool Invocation​

Modes​

Configuration​

Required Environment​

GCS Bucket​

Hooks Integration​

Error Handling​

Analysis Failures​

Fix Failures​

Deployment Failures​

Success Output​

Completion Checklist​

Failure Indicators​

When NOT to Use​

Anti-Patterns (Avoid)​

Principles​

Related Components​

Core Responsibilities​

Capabilities​

Analysis & Assessment​

Recommendation Generation​

Quality Validation​

Invocation Examples​

Direct Agent Call​

Via CODITECT Command​

Via MoE Routing​