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:

bash

# 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:

bash

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

Level 2:

bash

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

Level 3:

bash

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

Level 4:

bash

# 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:

bash

# 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

bash

# 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

bash

# 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