CODITECT Automation Standard

CAPaaS - Coditect Agentic Platform as a Service Copyright 2026 AZ1.AI Inc. All Rights Reserved

Version: 1.1.0 Status: ACTIVE Last Updated: 2026-01-03

---

Core Philosophy

Full automation with minimal human intervention.

Detect what's needed, set it up, execute. No "please run X first" instructions.

---

Foundational Principles

These principles guide ALL CODITECT development and automation:

1. Recycle, Extend, Re-Use, Create When Necessary

Priority Order:
1. RECYCLE - Use existing component as-is
2. EXTEND  - Add capability to existing component
3. RE-USE  - Adapt existing pattern for new context
4. CREATE  - Build new only when above options exhausted

2. First Principles Approach

Base everything from first principles. Don't copy patterns blindly - understand WHY they exist.

Question	Before Action
What problem are we solving?	Define clearly before coding
Why does this solution work?	Understand the mechanism
What are the trade-offs?	Document explicitly
Is there a simpler way?	Always ask

3. Keep It Simple

❌ WRONG: Complex solution for simple problem
❌ WRONG: Over-engineered "just in case"
✅ RIGHT: Simplest solution that solves the problem
✅ RIGHT: Optimize for edge cases only when they occur

YAGNI (You Aren't Gonna Need It): Don't build for hypothetical future requirements.

4. Separation of Concerns

Each component has ONE clear responsibility:

Component	Responsibility
/submodule-init	Submodule lifecycle ONLY
/component-create	Component creation ONLY
/classify	Document classification ONLY
Agent	Single domain expertise
Skill	Single capability

Cross-cutting concerns (logging, error handling) use shared utilities.

5. Eliminate Ambiguity

❌ WRONG: "Process the data" (what data? what process?)
✅ RIGHT: "Parse JSON from stdin, validate schema, output to stdout"

❌ WRONG: "Handle errors appropriately" (how?)
✅ RIGHT: "On network timeout, retry 3x with exponential backoff; on auth failure, return 401"

6. Clear, Understandable, Explainable

Every automation must be:

Quality	Test
Clear	A new developer understands in <5 minutes
Understandable	Intent obvious from reading code/docs
Explainable	Can articulate WHY every decision was made

7. No Action Without Understanding

❌ WRONG: Copy-paste solution without understanding
❌ WRONG: "It works, ship it" without knowing why
✅ RIGHT: Understand mechanism before implementing
✅ RIGHT: Can explain every line of code

8. No Assumptions Without Confirmation

Situation	Action
Unclear requirements	ASK before implementing
Multiple valid approaches	CONFIRM preferred approach
Edge case behavior	VERIFY expected outcome
Destructive operation	REQUIRE explicit confirmation

9. Based on Facts, Cross-Check

❌ WRONG: "I think this is how it works"
✅ RIGHT: "Documentation states X (source: URL)"
✅ RIGHT: "Tested and verified behavior is Y"

Cross-check sources:

1. Official documentation
2. Source code
3. Test results
4. Multiple independent sources

10. Research When in Doubt

Always use web search for latest understanding:

# Include recent years in searches
"Kubernetes best practices 2024 2025 2026"
"Python async patterns latest"
"GCP Cloud Run pricing current"

Research Priority
1. Official docs (2024-2026)
2. Authoritative blogs (2024-2026)
3. Stack Overflow (verified answers)
4. GitHub issues/discussions

11. Single Source of Truth (SSOT)

Every piece of information exists in exactly ONE authoritative location.

❌ WRONG: Task tracked in TASKLIST.md AND PROJECT-PLAN.md AND PILOT-PLAN.md
❌ WRONG: Configuration in config.json AND .env AND hardcoded
✅ RIGHT: One authoritative source, others reference it
✅ RIGHT: PILOT-PARALLEL-EXECUTION-PLAN.md is THE task source of truth

SSOT Hierarchy for CODITECT:

Layer	Document	Purpose
Strategic	PROJECT-PLAN.md	Vision, milestones, budget, timeline
Tactical	PILOT-PARALLEL-EXECUTION-PLAN.md	Active tasks (SSOT for work items)
Archive	archive/*.md	Historical record only

SSOT Enforcement:

1. Never duplicate task tracking - One plan, one checkbox
2. Reference, don't copy - Link to source, don't replicate
3. Archive completed phases - Move, don't maintain in multiple places
4. Rotate execution plans - Archive when phase completes

Deprecated (January 2026):

• TASKLIST.md - Consolidated into PILOT plan
• TASKLIST-WITH-CHECKBOXES.md template - Use PILOT plan format

12. Action-Level Task Tracking

Every tool call MUST include the task ID in its description.

❌ WRONG: Bash(description="Check migration status")
❌ WRONG: Bash(description="List files in directory")
✅ RIGHT: Bash(description="A.9.1.3: Check migration status")
✅ RIGHT: Bash(description="A.9.1.3: Run Django migrate for context app")

Format: {Task ID}: {Action Description}

Tool	Format
Bash	Bash(description="{Task ID}: {action}")
Read	Comment: "Reading for {Task ID}"
Edit	Comment: "{Task ID}: Updated X"
Glob/Grep	Comment: "{Task ID}: Finding X"

Why This Matters:

1. Audit Trail - Every action linked to a task
2. Session Logs - Auto-correlate actions to tasks
3. Retrospective Analysis - Understand task execution patterns
4. Cloud Sync - Required for TaskTracking model sync

Enforcement:

• Hook: task-tracking-enforcer.py validates task ID presence
• Level: strict blocks operations without task IDs
• Level: soft warns but allows (default)

Full Protocol: CODITECT-STANDARD-TASK-ID-PROTOCOL.md

---

The Five Automation Principles

1. Self-Provisioning

Automation MUST provision its own dependencies.

❌ WRONG: "Please install X before running this script"
❌ WRONG: "Error: dependency not found"
✅ RIGHT: Detect missing dependency → Install it → Continue execution

Implementation Pattern:

# Check if dependency exists
if ! command -v tool &> /dev/null; then
    info "Installing tool..."
    install_tool
fi

# Check if venv exists
if [ ! -d ".venv" ]; then
    info "Creating virtual environment..."
    python3 -m venv .venv
fi

# Check if packages installed
if ! python3 -c "import package" 2>/dev/null; then
    info "Installing requirements..."
    pip install -r requirements.txt
fi

2. Search Before Create

ALWAYS search for existing implementations before creating new ones.

❌ WRONG: Create new component without checking if similar exists
✅ RIGHT: Search → Find similar → Extend OR Create new if none exists

Implementation Pattern:

# Before creating agent
grep -r "similar-capability" agents/ skills/ commands/

# Before creating script
ls scripts/*similar* 2>/dev/null

# Before creating workflow
find workflows/ -name "*similar*"

Decision Tree:

Does similar component exist?
├── YES → Can it be extended?
│   ├── YES → Extend existing component
│   └── NO → Document why new component needed, then create
└── NO → Create new component

3. Extend Don't Duplicate

Prefer extending existing capabilities over creating parallel implementations.

❌ WRONG: Create classify-v2.py alongside classify.py
✅ RIGHT: Add new capability to classify.py with backward compatibility

When Extension is Required:

• New feature fits existing component's purpose
• Existing component is actively maintained
• Extension doesn't break existing functionality

When New Component is Required:

• Fundamentally different purpose
• Existing component is deprecated
• Extension would create confusion
• Document the decision in ADR

4. Inform and Confirm Destructive Actions

Human confirmation required ONLY for potentially destructive operations.

Action Type	Confirmation Required
Create file	NO - Inform only
Read file	NO
Edit file	NO - Inform only
Delete file	YES - Explicit confirmation
Install dependency	NO - Inform only
Create directory	NO - Inform only
Remove directory	YES - Explicit confirmation
Git push	NO - Inform only
Git push --force	YES - Explicit confirmation
Database write	NO - Inform only
Database delete	YES - Explicit confirmation
Deploy to production	YES - Explicit confirmation

Inform Pattern (Non-Destructive):

info "Creating virtual environment..."
python3 -m venv .venv
success "Virtual environment created"

Confirm Pattern (Destructive):

warning "This will delete 15 files in /path/to/dir"
if confirm "Proceed with deletion?"; then
    rm -rf /path/to/dir/*
    success "Files deleted"
else
    info "Aborted by user"
fi

5. Complete Execution Chain

Every automation must complete its full execution chain without manual intervention.

❌ WRONG:
   Step 1: Create component ✓
   Step 2: "Now run: python3 scripts/register.py"
   Step 3: "Then run: python3 scripts/classify.py"

✅ RIGHT:
   Step 1: Create component ✓
   Step 2: Register component ✓ (automatic)
   Step 3: Classify component ✓ (automatic)
   DONE: Component ready to use

Implementation Pattern:

main() {
    create_component      # Step 1
    update_inventory      # Step 2 (automatic)
    register_activate     # Step 3 (automatic)
    classify_component    # Step 4 (automatic)
    print_summary         # Done - ready to use
}

---

Automation Checklist

Before releasing any automation, verify:

Self-Provisioning

• Dependencies are auto-installed if missing
• Virtual environments are auto-created if missing
• Configuration files are auto-generated with defaults
• Required directories are auto-created

Search Before Create

• Similar components were searched before creation
• Extension of existing was considered
• Decision to create new is documented if applicable

Non-Destructive Operations

• User is informed of actions being taken
• No confirmation dialogs for safe operations
• Progress is clearly displayed

Destructive Operations

• User confirmation is required
• Clear warning about what will be affected
• Abort option is available
• Rollback is possible where applicable

Complete Execution

• No manual steps required between start and finish
• All sub-tasks execute automatically
• Final state is ready for immediate use
• Clear success/failure reporting

---

Error Handling

Recoverable Errors

Auto-recover and continue:

# Network timeout - retry
if ! download_file; then
    warning "Download failed, retrying..."
    sleep 2
    download_file || error "Download failed after retry"
fi

# Missing optional dependency - skip feature
if ! command -v optional_tool &> /dev/null; then
    warning "optional_tool not found, skipping feature X"
fi

Non-Recoverable Errors

Fail fast with clear message:

# Required dependency missing and can't install
if ! install_required_tool; then
    error "Cannot install required_tool. Please install manually:"
    error "  brew install required_tool"
    error "  OR: apt-get install required_tool"
    exit 1
fi

---

Examples

Good: Self-Provisioning Script

#!/bin/bash
# component-create.sh - Fully autonomous component creation

ensure_venv() {
    if [ ! -d ".venv" ]; then
        info "Creating virtual environment..."
        python3 -m venv .venv
    fi
    source .venv/bin/activate

    if ! python3 -c "import sentence_transformers" 2>/dev/null; then
        info "Installing dependencies..."
        pip install -q -r requirements.txt
    fi
}

main() {
    ensure_venv                    # Auto-provision
    create_component "$@"          # Create
    update_inventory               # Auto-register
    register_and_activate          # Auto-activate
    classify_component             # Auto-classify
    success "Component ready to use"
}

Bad: Manual Steps Required

#!/bin/bash
# DON'T DO THIS

echo "Before running this script:"
echo "1. Create venv: python3 -m venv .venv"
echo "2. Activate: source .venv/bin/activate"
echo "3. Install deps: pip install -r requirements.txt"
echo ""
echo "Then run this script again."
exit 1

---

Integration with CLAUDE.md

Add to root CLAUDE.md:

## Automation Principles

All CODITECT automation follows these core principles:

1. **Self-Provisioning** - Auto-install dependencies
2. **Search Before Create** - Extend existing, don't duplicate
3. **Inform Non-Destructive** - No confirmation for safe ops
4. **Confirm Destructive** - Explicit approval for deletions
5. **Complete Execution** - No manual steps required

See: `coditect-core-standards/CODITECT-STANDARD-AUTOMATION.md`

---

Compliance

All CODITECT scripts, commands, and workflows MUST comply with this standard.

Audit Criteria

Criterion	Weight	Pass Threshold
Self-Provisioning	25%	100%
Search Before Create	20%	Documented
Inform/Confirm Pattern	25%	100%
Complete Execution	30%	100%

Minimum Passing Score: 90%

---

References

• CODITECT-STANDARD-SCRIPTS.md - Script standards
• CODITECT-STANDARD-COMMANDS.md - Command standards
• ADR-049: Component Creation Lifecycle
• ADR-050: Submodule Initialization Lifecycle

---

Version: 1.1.0 Created: 2026-01-03 Author: CODITECT Team Owner: AZ1.AI INC