archie-deep-scan

name	archie-deep-scan
description	Comprehensive architecture baseline scan. Two-wave AI analysis producing blueprint.json, per-folder CLAUDE.md, AI-synthesized rules, and health metrics. Use for first-time baselines or major refactors.

Archie Deep Scan — Comprehensive Architecture Baseline

Run a comprehensive architecture analysis. Produces full blueprint, per-folder CLAUDE.md, rules, and health metrics.

Modes:

• {{COMMAND_PREFIX}}archie-deep-scan — full baseline from step 1 (default, proven workflow)
• {{COMMAND_PREFIX}}archie-deep-scan --incremental — only process files changed since last deep scan (fast, 3-6 min)
• {{COMMAND_PREFIX}}archie-deep-scan --comprehensive — lift quotas + scope caps for a fully comprehensive baseline (slower). Composes with --incremental.
• {{COMMAND_PREFIX}}archie-deep-scan --from N — resume from step N (runs N through 9)
• {{COMMAND_PREFIX}}archie-deep-scan --continue — resume from where the last run stopped

Prerequisites: Run npx @bitraptors/archie first to install the scripts. If .archie/scanner.py doesn't exist, tell the user to run npx @bitraptors/archie and try again.

Recovery when a run stalls or fails (network drop, sub-agent timeout, /compact interruption, etc.): The only valid recovery options are listed above — --continue, --from N, or a fresh full run. There is no separate "fast scan" or "light scan" command — {{COMMAND_PREFIX}}archie-deep-scan is the single entry point for architecture analysis. If sub-agents timed out, prefer --continue (resumes from the last completed step using deep_scan_state.json). If specific Wave 1 outputs were lost from /tmp/, use --from 3 to redo Wave 1. Do not invent fallback slash commands. If the existing .archie/blueprint.json is recent enough for the current task, skipping the rescan is a valid choice; say so explicitly.

Update notice (run before anything else, silent unless action needed)

python3 .archie/update_check.py check 2>/dev/null

If output is non-empty:

• UPGRADE_AVAILABLE old new → tell the user once at the top of your reply: "Archie {new} is available (installed: {old}). Upgrade: npx @bitraptors/archie@latest \"$PWD\"". Then continue with the scan — do not block.
• JUST_UPGRADED old new → say "Archie upgraded {old} → {new}." once, then proceed.

If output is empty: proceed silently. This is informational only.

Telemetry consent (one-time, run before anything else)

Read and follow {{WORKFLOW_ROOT}}/_shared/telemetry-consent.md. It checks whether this machine has been asked about anonymous usage telemetry and, if not, presents a one-time interactive opt-in. It self-skips after the first answer and on non-interactive sessions.

CRITICAL CONSTRAINT: Never write inline Python. Do NOT use python3 -c "..." or any ad-hoc scripting to inspect, parse, or transform JSON. Every operation has a dedicated command:

• Normalize blueprint: python3 .archie/finalize.py "$PROJECT_ROOT" --normalize-only
• Append health history: python3 .archie/measure_health.py "$PROJECT_ROOT" --append-history --scan-type deep
• Inspect any JSON file: python3 .archie/intent_layer.py inspect "$PROJECT_ROOT" <filename>
• Query a specific field: python3 .archie/intent_layer.py inspect "$PROJECT_ROOT" scan.json --query .frontend_ratio

If you need data not covered by these commands, proceed without it or ask the user. NEVER improvise Python.

Preamble: Determine starting step

Check the user's message (ARGUMENTS) for flags:

Depth (independent of the flags above): Parse this first, regardless of which flag branch runs below. If ARGUMENTS contains --comprehensive (the canonical form; a bare comprehensive is also accepted), set DEPTH=comprehensive. Otherwise set DEPTH=default.

Comprehensive Mode Contract (governs EVERY step when DEPTH=comprehensive)

This is the single global rule for comprehensive depth — it overrides any per-step count, everywhere, including steps that carry no explicit comprehensive clause.

Treat every item-count anywhere in this workflow — N-M, "up to N", "top N", "the N most", "soft floor of N", "a handful", "the most important" — as a FLOOR with no ceiling. Produce every item that genuinely meets its quality bar; never trim to a number, never stop at a "natural" count. The quality bar is unchanged: do NOT pad, invent, or weaken per-item rigor to inflate counts.

Only two limits survive comprehensive mode: (1) the architecture diagram stays 8-12 nodes (readability), and (2) the scripts' mechanical safety/context budgets (per-file read size, per-batch token budget, recursion). Everything else — rules, findings, pitfalls, decisions, trade-offs, components, guidelines, examples, naming examples, per-field prose length — is uncapped.

Whenever a step dispatches a sub-agent in comprehensive depth, prepend the contract line shown at that dispatch site so the sub-agent inherits this rule.

If --from N is present (e.g., {{COMMAND_PREFIX}}archie-deep-scan --from 5):

1. If N is not between 1 and 9, tell the user the valid range is 1-9 (the pipeline has 9 steps; older versions had a step 10, which no longer exists) and stop.
2. Set START_STEP = N (the number after --from) and RESUME_ACTION=resume (so the Resume Prelude rehydrates shell variables from deep_scan_state.run_context).
3. Validate prerequisites exist:

python3 .archie/intent_layer.py deep-scan-state "$PROJECT_ROOT" check-prereqs N

4. If check fails, tell the user which files are missing and which earlier step to run.
5. If check passes, proceed. Do NOT call deep-scan-state init — it would wipe the state the Resume Prelude needs to read.

If --continue is present:

1. Read state (no prompt — --continue is an explicit opt-in):

LAST=$(python3 .archie/intent_layer.py inspect "$PROJECT_ROOT" deep_scan_state.json --query .last_completed 2>/dev/null)
STATUS=$(python3 .archie/intent_layer.py inspect "$PROJECT_ROOT" deep_scan_state.json --query .status 2>/dev/null)
[ -z "$LAST" ] || [ "$LAST" = "null" ] && LAST=0

2. If LAST == 0 or STATUS == "completed": print "No interrupted run found. Starting fresh from step 1." Set START_STEP=1, RESUME_ACTION=fresh, and run deep-scan-state init below.
3. Otherwise: Set START_STEP = LAST + 1, RESUME_ACTION=resume. Print "Resuming deep scan from step {START_STEP}.". Skip the init call.

If --incremental is present:

1. Check if .archie/blueprint.json exists. If not: print "No existing blueprint — running full baseline instead." Set SCAN_MODE = "full", START_STEP = 1, and proceed as default.
2. If blueprint exists, detect changes:

python3 .archie/intent_layer.py deep-scan-state "$PROJECT_ROOT" detect-changes

3. Read the JSON output:
   • If mode is "full" (threshold exceeded or no previous scan): print the reason and say "Running full baseline." Set SCAN_MODE = "full", START_STEP = 1.
   • If mode is "incremental" and changed_count is 0: print "No files changed since last deep scan. Nothing to do." Exit.
   • If mode is "incremental": Set SCAN_MODE = "incremental". Save changed_files and affected_folders from the output. Print "Incremental deep scan: N files changed. Analyzing changes only." Set START_STEP = 1.
4. Initialize state, then persist the run depth + scan mode:

python3 .archie/intent_layer.py deep-scan-state "$PROJECT_ROOT" init
python3 .archie/intent_layer.py deep-scan-state "$PROJECT_ROOT" save-run-context --depth "$DEPTH" --scan-mode "$SCAN_MODE"

If no flags (default — detect interrupted run, otherwise full baseline):

Before assuming a fresh run, check whether a previous deep-scan was left unfinished. If so, offer the user a choice instead of silently wiping their work.

1. Read state:

LAST=$(python3 .archie/intent_layer.py inspect "$PROJECT_ROOT" deep_scan_state.json --query .last_completed 2>/dev/null)
STATUS=$(python3 .archie/intent_layer.py inspect "$PROJECT_ROOT" deep_scan_state.json --query .status 2>/dev/null)
[ -z "$LAST" ] || [ "$LAST" = "null" ] && LAST=0

2. If LAST == 0 or STATUS == "completed" → no interrupted run. Proceed as fresh:

   • Set SCAN_MODE=full, START_STEP=1, RESUME_ACTION=fresh.
   • Initialize state, then persist the run depth + scan mode:

     python3 .archie/intent_layer.py deep-scan-state "$PROJECT_ROOT" init
     python3 .archie/intent_layer.py deep-scan-state "$PROJECT_ROOT" save-run-context --depth "$DEPTH" --scan-mode "$SCAN_MODE"
     

3. Otherwise (LAST > 0 and STATUS == "in_progress") → an interrupted run exists. Figure out which step stopped it and where enrichment state stands:

   ENRICH_DONE=$(python3 .archie/intent_layer.py inspect "$PROJECT_ROOT" enrich_state.json --query '.done|length' 2>/dev/null)
   [ -z "$ENRICH_DONE" ] || [ "$ENRICH_DONE" = "null" ] && ENRICH_DONE=0
   

   Build a human-readable label for the last completed step:

   LAST	step_name
   1	scanner
   2	read accumulated knowledge
   3	Wave 1 analytical agents
   4	Wave 1 merge
   5	Wave 2 reasoning agents (Design/Risk/Overview)
   6	AI rule synthesis
   7	Intent Layer
   8	Cleanup
   9	Finalize (health + telemetry)

   Ask the user how to proceed — {{>ask_user}}:

   • question: (build dynamically) "A previous deep-scan stopped after Step {LAST} ({step_name})." — and if ENRICH_DONE > 0, append " The Intent Layer got {ENRICH_DONE} folders in before stopping." — then "What do you want to do?"
   • header: "Resume"
   • multiSelect: false
   • options (exactly these two labels):
     1. label Resume — description Continue from Step {LAST+1}. Preserves all completed work, including any partial Intent Layer batches. Recommended.
     2. label Fresh start — description Discard all progress and restart from Step 1. Erases the interrupted blueprint, Wave 1 outputs, and the partial Intent Layer state. Use only if the codebase changed significantly.

   Map the answer:

   • Resume → Set START_STEP = LAST + 1, RESUME_ACTION=resume. Skip init. Print "Resuming from Step {START_STEP}.".
   • Fresh start → Reset everything and start over:

     python3 .archie/intent_layer.py deep-scan-state "$PROJECT_ROOT" init
     python3 .archie/intent_layer.py reset-state "$PROJECT_ROOT"
     rm -f .archie/tmp/archie_enrichment_${PROJECT_NAME}_*.json .archie/tmp/archie_intent_prompt_${PROJECT_NAME}_*.txt
     

     reset-state wipes both .archie/enrich_state.json and the .archie/enrichments/ directory — no rm -rf needed in the slash-command layer (keeps the command inside the default Bash permission allowlist so this runs prompt-free). Set SCAN_MODE=full, START_STEP=1, RESUME_ACTION=fresh. Print "Starting fresh. Previous progress discarded.". Then persist the run depth + scan mode:

     python3 .archie/intent_layer.py deep-scan-state "$PROJECT_ROOT" save-run-context --depth "$DEPTH" --scan-mode "$SCAN_MODE"
     

4. Regardless of branch above, RESUME_ACTION is now set. It gates the Resume Prelude (below) and the Step 7 delta (passes RESUME_INTENT to the Intent Layer).

For every step below:

• If the step number < START_STEP, skip it entirely.
• If SCAN_MODE is not set, it defaults to "full" (all existing behavior unchanged).
• Do NOT ask the user any questions during Steps 1–9. Do NOT offer to skip, reduce scope, or present alternatives for any step. Execute every step fully as documented. This rule applies ONLY to Steps 1–9. It does NOT apply to Phase 0 / Activation: the scope prompt (Step C) and Intent Layer prompt (Step E) in scope_resolution.md are mandatory decision gates and MUST still be asked — see below.

Activation — read these before running any step

Before executing any step, Read these files in order. They establish the conventions and Phase 0 variables (SCOPE, WORKSPACES, MONOREPO_TYPE, PROJECT_ROOT, PROJECT_NAME) that every step assumes are in place.

All paths below are relative to the project root (your cwd). The fragments live alongside this orchestrator under {{WORKFLOW_ROOT}}/deep-scan/.

1. {{WORKFLOW_ROOT}}/deep-scan/fragments/telemetry-conventions.md — telemetry mark / finish / write contract used by every step.
2. {{WORKFLOW_ROOT}}/deep-scan/fragments/compact-resume-contract.md — how the pipeline survives /compact mid-run via .archie/deep_scan_state.json.
3. If RESUME_ACTION=resume: {{WORKFLOW_ROOT}}/deep-scan/fragments/resume-prelude.md — rehydrates shell variables from persisted state.
4. {{WORKFLOW_ROOT}}/_shared/scope_resolution.md — Phase 0 scope resolution. Establishes PROJECT_ROOT, PROJECT_NAME, SCOPE, WORKSPACES, MONOREPO_TYPE.

Step-by-step routing

Before starting any Step N, Read the file in the "Load this file" column. The router does not contain step content — each step is a self-contained file. If START_STEP > N (the Preamble decided to skip earlier steps), do not Read or run those steps.

Step	What it does	Load this file before starting
1	Run the scanner	{{WORKFLOW_ROOT}}/deep-scan/steps/step-1-scanner.md
2	Read accumulated knowledge from prior runs	{{WORKFLOW_ROOT}}/deep-scan/steps/step-2-read-scan.md
3	Wave 1 — spawn parallel analytical agents	{{WORKFLOW_ROOT}}/deep-scan/steps/step-3-wave1/orchestration.md
4	Save & merge Wave 1 output	{{WORKFLOW_ROOT}}/deep-scan/steps/step-4-merge.md
5	Wave 2 — reasoning agents: Design · Risk · Overview ({{REASONING_MODEL}}, parallel)	{{WORKFLOW_ROOT}}/deep-scan/steps/step-5-wave2-reasoning.md
6	AI rule synthesis	{{WORKFLOW_ROOT}}/deep-scan/steps/step-6-rule-synthesis.md
7	Intent Layer — per-folder CLAUDE.md	{{WORKFLOW_ROOT}}/deep-scan/steps/step-7-intent-layer.md
8	Cleanup	{{WORKFLOW_ROOT}}/deep-scan/steps/step-8-cleanup.md
9	Finalize — health metrics, baseline, telemetry flush	{{WORKFLOW_ROOT}}/deep-scan/steps/step-9-finalize.md

Step 3's orchestration.md in turn references four sub-agent prompt files plus a shared grounding-rules.md (all under {{WORKFLOW_ROOT}}/deep-scan/steps/step-3-wave1/) — read those as the orchestration instructs.