Justfile Maturity Model

Justfile Maturity Model

Five levels. Start at 0. Add levels as needed. YAGNI enforcement.

Levels

Level 0: Baseline (EVERY project)

Commands: 9 required

• default, dev-install, format, lint, typecheck, test, coverage, check-all, clean

Criteria:

• All commands present (stub or implement)
• Exact comment strings
• check-all runs format → lint → typecheck → coverage
• just check-all succeeds or fails meaningfully

When: All projects, no exceptions

Skill: justfile-interface

Level 1: Quality Gates (CI matters)

Commands: +4

• test-watch - Continuous test execution
• integration-test - Integration tests, no threshold, never blocks
• complexity - Detailed complexity report
• loc - Largest files by lines of code

Criteria:

• Test separation (unit vs integration)
• Integration tests marked/tagged
• Complexity reporting (informational, not blocking)

When:

• Setting up CI/CD
• Multiple developers
• Need fast feedback loop

Skill: justfile-quality-patterns

Level 2: Security (Deploying)

Commands: +4

• vulns - Vulnerability scanning
• lic - License compliance
• sbom - Software bill of materials
• doctor - Environment health check

Criteria:

• Multi-tier scanning (critical/medium/high)
• License checking (prod vs dev separation)
• SBOM generation (CycloneDX format)
• Environment validation

When:

• Deploying to production
• Security requirements
• Compliance needs

Skill: justfile-security-patterns

Level 3: Advanced (Production systems)

Commands: +6+

• test-smart - Git-aware test execution
• deploy - Deploy to environment
• deploy-api, deploy-web - Partial deploys
• migrate - Database migrations
• logs - Service logs
• status - Deployment health

Criteria:

• Git-aware testing (conditional execution)
• Deployment integration (cloud provider)
• Migration management
• Observability commands

When:

• Production deployment workflows
• Database-backed applications
• Cloud-native systems

Skill: justfile-advanced-patterns

Level 4: Polyglot (Multi-language)

Structure: Root + subprojects

Root commands: Subset (orchestration)

• dev-install, check-all, clean, build, deps, vulns, lic, sbom
• Delegates to subprojects via _run-all

Subproject commands: Full interface

• Each subproject implements level 0+ independently

Criteria:

• Root orchestrates, doesn't duplicate
• Each subproject standalone (cd api && just check-all)
• _run-all fails fast
• Clean delegation pattern

When:

• Multiple languages (Python + JavaScript, etc.)
• Microservices architecture
• Monorepo structure

Skill: justfile-polyglot-patterns

Assessment

Check Current Level

Level 0:

# All 9 baseline commands present?
for cmd in default dev-install format lint typecheck test coverage check-all clean; do
  grep -q "^$cmd:" justfile || echo "Missing: $cmd"
done

# check-all correct?
grep -q "^check-all: format lint typecheck coverage$" justfile || echo "check-all wrong"

# Comments exact?
# (check against justfile-interface skill)

Level 1:

# Quality commands present?
grep -q "^test-watch:" justfile
grep -q "^integration-test:" justfile
grep -q "^complexity:" justfile
grep -q "^loc:" justfile

Level 2:

# Security commands present?
grep -q "^vulns:" justfile
grep -q "^lic:" justfile
grep -q "^sbom:" justfile
grep -q "^doctor:" justfile

Level 3:

# Advanced commands present?
grep -q "^test-smart:" justfile
grep -q "^deploy:" justfile
grep -q "^migrate:" justfile

Level 4:

# Polyglot structure?
test -f justfile && test -f api/justfile && test -f web/justfile
grep -q "_run-all" justfile

Progression

When to Stop

Don't add level if:

• Not using feature (no CI → skip level 1)
• No deployment → skip level 3
• Single language → skip level 4

YAGNI applies.

Non-Linear Progression

Can add specific patterns without full level:

# At level 0, add test-smart only
/just-upgrade test-smart

# At level 1, add deployment only
/just-upgrade deploy

Typical Paths

Web application: 0 → 1 → 2 → 3 (quality → security → deployment)

Library: 0 → 1 → 2 (quality → security, no deployment)

Monorepo: 0 → 1 → 4 → 2 → 3 (baseline → quality → polyglot → security → deployment)

Solo project: 0 → 2 (baseline → security, skip quality overhead)

Upgrade Strategy

Assess First

Always run /just-assess before upgrade. Shows:

• Current level
• Missing commands for current level
• Non-standard comment strings
• Recommended next level or patterns

Incremental Addition

# Complete current level first
/just-assess
# Output: Level 0 (8/9 commands, missing: integration-test)

/just-refactor
# Adds missing baseline command

# Then upgrade
/just-upgrade 1
# Adds level 1 quality commands

Pattern-Specific

# Add single pattern
/just-upgrade test-smart
# Adds test-smart from level 3, doesn't add full level 3

# Add multiple patterns
/just-upgrade test-smart deploy
# Adds both patterns

Validation

Each level has success criteria:

Level 0: All baseline present, check-all works Level 1: Test separation enforced, integration-test never blocks Level 2: Security scans run, licenses checked Level 3: Deployment works, migrations tracked Level 4: All subprojects pass check-all independently

Anti-Patterns

Don't:

• Skip level 0 (baseline non-negotiable)
• Add all levels (YAGNI)
• Mix implementations (pick one stack)
• Ignore exact comments (validation depends on these)
• Block on integration tests (always report-only)

Do:

• Complete current level before advancing
• Add patterns as needed
• Validate after each change
• Stub unimplemented commands
• Follow stack-specific implementations