xu-jin-cs/dsh-skills

ArchMap Architecture Mapping Agent

Terminal-native agent, no web interface. Zero-parameter invocation automatically dispatches to full/lite mode, and also supports explicit modes for incremental requirement impact analysis, sync updates, diff impact analysis, etc.

Installation and Dependencies

Before first use, run pip3 install -r requirements.txt in the skill root directory (see README.md). The sentence-transformers package is an optional dependency; when missing, vector recognition automatically falls back to local hashing-based vectorization, keeping functionality intact with slightly reduced accuracy.

Invocation

/archmap <project-path>                        # Zero-parameter auto-dispatch (recommended)
/archmap <project-path> full | lite [notes]    # Explicit mode fallback
/archmap <project-path> <requirement-text>
/archmap <project-path> sync
/archmap <project-path> diff [modification-notes]

Examples:

/archmap /Users/xujin/projects/my-app
/archmap /Users/xujin/projects/my-app New user reward system, involving login API and role table
/archmap /Users/xujin/projects/my-app sync

Mode Routing (Zero-parameter Auto-dispatch, Added 2026-08-12)

Zero-parameter call /archmap <project-path> automatically dispatches based on whether a baseline exists, with no manual toggle:

• No baseline (archmap/full_index.json does not exist) → Automatically executes full initialization
• Baseline exists → Automatically executes lite minimal incremental mode (default for daily iterations, see Mode G)
• Special scenarios use explicit fallback: full / lite explicit keywords force the mode (use full after major refactoring to regenerate the complete graph, without deleting the baseline directory)

Mode List

Mode A: Full Analysis (project path only)

When the path is the project root:

1. Perform full source code scan
2. Split modules by business directory, multi-threaded Worker parsing
3. Aggregate assets at the parent, mark shared APIs/storage, generate vector cache
4. Generate Mermaid text diagrams and Markdown reports 01~09
5. Atomically write results to <project-path>/archmap/
6. Output product paths and summary

Output paths:

<project-path>/archmap/
├── full_index.json          # Complete architecture baseline
├── vector_cache.json        # Module vector cache
├── 01_executive_summary.md
├── 02_architecture_diagram.md           # Mermaid text
├── 03_data_flow_diagram.md
├── 04_sequence_diagram.md
├── 05_module_asset_inventory.md
├── 06_API_asset_inventory.md
├── 07_storage_asset_inventory.md
├── 08_dependency_matrix.md
└── 09_granularity_validation_report.md

Mode B: Incremental Impact Analysis (project path + requirement text)

Input a project path that already has a baseline, along with requirement text. Before matching requirements, this mode first synchronizes actual changes in the source code, so calling /archmap <path> <requirement> triggers a postmortem integration:

1. Read vector_cache.json, full_index.json, module_hashes.json from <project-path>/archmap/
2. Compare current source code with the module content fingerprints (SHA256) from the last sync, identifying changed/new modules
3. Only re-parse changed modules and merge them back into the baseline; unchanged modules directly reuse baseline data
4. Vectorize the requirement text and perform cosine similarity matching against the latest module vectors
5. Distinguish high-confidence / low-confidence suspected modules, recursively traverse upstream and downstream dependencies
6. Only start Worker parsing for new/modified modules hit by the requirement; existing dependency modules directly reuse baseline data without calling LLM
7. For hit modules, perform precise intra-module localization: identify involved files, function/class names, API routes, route-to-file mappings, and sort by relevance to requirement keywords
8. Recall Engine (recall_engine): on top of vector hits, uses two types of deterministic signals to expand the affected set, not constrained by vector thresholds—① Route supply-demand closure (routes referenced by affected modules → defining modules, and referencing modules of its defined routes) ② Requirement route keyword hard matching (requirement terms undergo CN→EN expansion, directly hitting module defined routes). Outputs match_sources annotation for each module's hit source (vector/keyword/route_closure/route_keyword)
9. Merge and update the baseline, generate precise_analysis.json impact file + precise_meta.json prediction metadata (requirement text, hit source, baseline hash fingerprint)
10. Output affected modules, APIs, storage, and involved file list to guide targeted development

Note: Postmortem sync is only triggered when "existing baseline + new requirement"; first-time full analysis of a new project does not perform sync.

Output: Update full_index.json, vector_cache.json in the baseline folder, and add precise_analysis.json:

[
  {
    "module_id": "src_users",
    "module_path": "src/users/",
    "files": [
      {
        "file_path": "api.py",
        "functions": ["list_users", "get_user"],
        "classes": [],
        "routes": ["/api/users", "/api/users/<id>"],
        "relevance": 0.6
      }
    ],
    "route_to_files": {
      "/api/users": ["api.py"],
      "/api/users/<id>": ["api.py"]
    },
    "keyword_matches": ["api.py"]
  }
]

Mode C: Sync Update (project path + sync)

After a project has completed full analysis and entered continuous development, new code needs to be merged back into the existing baseline without re-running full analysis.

Invocation:

/archmap <project-path> sync

Execution flow:

1. Read full_index.json, vector_cache.json, module_hashes.json from <project-path>/archmap/
2. Compare current source code with the module content fingerprints (SHA256) from the last sync
3. Only re-parse new/modified modules; already-parsed unchanged modules directly reuse baseline data without calling LLM
4. Remove deleted modules and their vectors from the baseline
5. Re-generate Mermaid diagrams and Markdown reports 01~09
6. Atomically update full_index.json, vector_cache.json, module_hashes.json and report files
7. Recall Validation (recall_engine): if the baseline contains prediction files from the last impact analysis (precise_analysis.json + precise_meta.json), automatically compare predicted modules with the actual changed modules:
   • Changes exist → produce recall_report.json (hit rate, missed modules and attribution: route_keyword_miss / closure_miss / vector_miss), append to recall_history.jsonl, then consume the prediction files
   • No changes → retain predictions for verification on next sync after development is complete
   • Baseline hash fingerprint mismatch (predictions belong to an ended old development cycle) → discard stale predictions, do not verify

Output: Baseline folder content fully refreshed, structure same as Mode A, but only consumes parsing cost for changed modules. When predictions are pending verification, recall_report.json and recall_history.jsonl are added.

<project-path>/archmap/
├── full_index.json          # Baseline with new/modified modules merged
├── vector_cache.json        # Only recalculated vectors for changed modules
├── module_hashes.json       # Latest module content fingerprints
├── 01_executive_summary.md
├── 02_architecture_diagram.md
├── 03_data_flow_diagram.md
├── 04_sequence_diagram.md
├── 05_module_asset_inventory.md
├── 06_API_asset_inventory.md
├── 07_storage_asset_inventory.md
├── 08_dependency_matrix.md
└── 09_granularity_validation_report.md

Typical usage rhythm:

1. First time: /archmap /path/to/project
2. Develop new features and modify source code
3. Postmortem sync: /archmap /path/to/project sync
4. Locate impact: /archmap /path/to/project Add points functionality

Mode D: ETL Bottom-Layer Rule Exploration (Auto-triggered)

For projects with ETL characteristic directories (any of tongue_diagnosis/etl / etl_config / etl/core exists), full analysis and sync updates automatically generate 7 ETL change maintenance service artifacts, written to <project-path>/archmap/etl_rules/:

#	Artifact	Content
①	ETL_Rule_Index_Table_of_Contents.md	7-tier directory tree (Preprocessing Cleaning→Chunk Splitting→Vectorization Write→Consistency Reconciliation→Isolation Storage→Exception Retry→ETL Orchestration) + unique rule codes (ETL-CHUNK-01, etc.) + keyword tags + quick search index + 7-step usage flow
②	details/ETL-{code}.md (1 per rule)	Uniform 7 sections: Rule Base Identification / Complete Bottom-Level Execution Logic / Precise Source Code Location / Input-Output Constraints / Related Dependency Rules / Historical Change Records / Test Validation Standards
③	etl_rule_mapping.json	ETL rule-code-configuration mapping table (machine-readable)
④	ETL_Rule_Dependency_Graph.md	Mermaid dependency graph + text impact list + impact level (High/Medium/Low)
⑤	ETL_Global_Parameter_Baseline_Table.md	All rule parameter baseline values + configuration file sources
⑥	ETL_Rule_Change_Risk_Assessment_Checklist.md	All rule risk levels/descriptions/regression tests + pre-change actions
⑦	etl_rule_search_index.json	Machine search index (rule entries + keyword quick index keyword → rule code)
⑧	ETL_Configuration_Contract_Alignment_Report.md + config_contract_report.json	Configuration-code contract drift detection (regular alignment): yaml key existence + read/use feature string grep → aligned (wired up) / unused (dead config) / stale (code remnant) / missing_from_yaml (contract inconsistency) + remediation suggestions

Key points:

• Regular Alignment (Configuration Contract Drift): After changing configs or code consumption points, run /archmap <project-path> sync; report ⑧ automatically refreshes each field's status (field exists ≠ active: unused/stale need wiring or cleanup per suggestions). Existing baseline drift examples: RRF weights not taking effect (rag_engine._rrf_fuse weights hardcoded 1.0), max_ctx_tokens config unwired, reconcile.enabled/batch_size dead config, embedding.yaml batch_size unconsumed
• Source code line numbers are resolved at runtime via function name/feature string grep; after code changes, /archmap <project-path> sync refreshes all line numbers and artifacts
• P0/P1/P2 Parsing Depth Levels (Phase 2, 2026-08-12): risk_level high→P0 deep parse (line numbers + config + contract), medium→P1 standard parse (line numbers), low→P2 lightweight parse (file existence check only, line numbers skipped and not counted in unresolved metrics); detail docs headers, index table of contents, mapping JSON, search index JSON all carry priority flags; summary contains priority_counts and parse_depth statistics; individual rules can override derivation with an explicit priority field in etl_rule_registry.py
• Backfill Convention (must run after modifying ETL rules/steps/configs): /archmap <project-path> sync automatically backfills three aspects—① Line numbers (grep real-time parse); ② Parameter baselines (etl.yaml/embedding.yaml/chunking.yaml read at runtime, corresponding rule parameters in ③⑤⑦ auto-refresh to current config values); ③ Semantic-level changes (rule rename/behavior change/risk level adjustment) — append a history record in etl_rule_registry.py then rerun sync to regenerate. Not running sync causes documentation to drift from code/config
• Search entry: read etl_rules/etl_rule_search_index.json (machine) or the index TOC keyword table (human)
• Detail docs contain a Test Validation Standards section; after modifying rules, run regression using the corresponding use case
• For custom ETL rule registry override mechanism, see the "Project-Level Configuration" section in README.md

Mode E: Test Design Input Assets

ArchMap's full analysis artifacts—architecture diagrams, data flow diagrams, sequence diagrams, asset inventories, dependency matrices—can be directly used as input for test-case-designer, driving test design based on the three elements of "node + branch + method."

Artifacts Consumable by Test Design

Artifact File	Test Design Purpose	Extracted Content
02_architecture_diagram.md	Identify system layers and module boundaries	Layer nodes (Trigger/Definition/Persistence/Engine/Validation)
03_data_flow_diagram.md	Identify end-to-end data flows	Data flow nodes, inputs/outputs, persistence targets
04_sequence_diagram.md	Identify call sequences and concurrency/wait relationships	Call sequences, sync/async boundaries, exception return points
05_module_asset_inventory.md	Identify functional modules and responsibilities	Module names, core functions, responsibility descriptions
06_API_asset_inventory.md	Identify API test nodes	Routes, methods, parameters, return structures, error codes
07_storage_asset_inventory.md	Identify data persistence test points	Storage types, fields, constraints, lifecycle
08_dependency_matrix.md	Identify change impact scope and regression range	Inter-module call relationships, shared APIs/storage
precise_analysis.json	Precisely locate test scope for incremental requirements	Changed modules, involved files, functions/routes, relevance

Test Design Input Standard Format

After reading the above artifacts, test-case-designer must reduce the information to the following standard structure (as a design intermediate artifact submitted for review alongside execution-list.json, not persisted as an archmap artifact—archmap engine only produces 01~09):

## Test Node Inventory

| Node ID | Node Name | Module | Function/Role | Input | Output | Persistence |
|---------|-----------|--------|---------------|-------|--------|-------------|
| N-001 | create_workflow_endpoint | webui.py | Create new workflow via Web UI | {name, mode} | flow.yml / SKILL.md / directory | New directory tree |
| N-002 | validate_flow_structure | workflow.py | Validate flow.yml structure correctness | flow_data | error list or empty list | None |
| N-003 | gate_a_check | engine.py | Pre-execution admission check | agent, state | passed/errors/log | engine_state.json |

## Branch Closure List

| Source Node | Branch Condition | True Branch | False Branch | Invalid Input | State Inconsistency |
|-------------|------------------|-------------|--------------|---------------|---------------------|
| N-001 | name empty? | Continue creation | Return 400 | Oversize/special characters | Parent directory not set |
| N-003 | All upstream complete? | Enter Gate B | blocked | Unknown node | Deliverable hash tampered |

## Test Method Mapping

| Node | Boundary Value (BV) | Equivalence Class (EC) | Domain Logic (DL) | Scenario (SC) | Exception (EX) | Compatibility (CP) | Interface Security (IS) |
|------|---------------------|------------------------|-------------------|----------------|-----------------|---------------------|-------------------------|
| N-001 | Name length boundaries | Valid/invalid names | Create→Generate→Return | Normal creation flow | Missing parent directory | — | Path traversal/special characters |
| N-003 | max_retry boundaries | Upstream complete/incomplete | Gate A→Execute→Gate B | Normal progression | Hash mismatch | With/without jsonschema | — |

Consumption for Incremental Scenarios

When a PM provides a new requirement:

1. Call /archmap <project-path> "requirement text" to generate/update precise_analysis.json.
2. test-case-designer first reads precise_analysis.json to identify changed modules and involved files.
3. Extract test nodes only for changed modules and their direct dependencies, avoiding full redesign.
4. In execution-list.json, mark use cases with baseline_affected: true for targeted regression.

Integration Contract with test-case-designer

test-case-designer has autonomous analysis capability; upon launch, it processes as follows:

1. Autonomously discover existing analysis results: Check if <project-path>/archmap/ exists and contains valid 02_architecture_diagram.md and 03_data_flow_diagram.md.
   • If they exist: Directly read artifacts 02~08 + precise_analysis.json (incremental scenario) as test design input, avoiding redundant analysis.
   • If they do not exist or are stale: Automatically call /archmap <project-path> (full) or /archmap <project-path> "requirement text" (incremental) to generate analysis results, then read them. The PM does not need to call archmap separately before testing.
2. Read 02_architecture_diagram.md + 03_data_flow_diagram.md + 04_sequence_diagram.md, identify system-level test nodes.
3. Read 05_module_asset_inventory.md + 06_API_asset_inventory.md + 07_storage_asset_inventory.md, identify module-level test nodes.
4. Read 08_dependency_matrix.md, identify inter-node dependencies and impact scope.
5. Output the reduced node/branch/method inventory as a design intermediate artifact (i.e., Rule 32 Step 1.8 "Test Node and Branch Inventory"), submitted for review alongside execution-list.json.

Mode F: Diff Impact Analysis (project path + diff, Added 2026-08-12)

Post-version-update differential impact analysis, providing authoritative diff input for downstream processes like white-box incremental testing. Git-independent (usable in repositories without git history), zero LLM calls, completes in seconds.

Execution timing (fixed checkpoint): Must be run once after feature additions/modifications are complete, before the review/sync phase. The current change (timestamp + modification content + line ranges + impact closure) is automatically recorded in the change history as input material for review; after acceptance, use sync to refresh the baseline and backfill 01~09 analysis documents—diff records, change history, and analysis documents together form a cohesive whole.

Invocation:

/archmap <project-path> diff
/archmap <project-path> diff This time added invalid parameter validation for the video speed change feature

Execution flow:

1. Read baseline directory line-level snapshot file_line_hashes.json (auto-written during full/sync; if no snapshot exists for first diff, initialize and prompt that comparison is possible from the next round)
2. Compare current line hashes against the snapshot file by file using difflib → output precise changed line ranges for changed files (1-based, merging adjacent ranges). Unchanged files only undergo hash comparison, no re-analysis
3. Dependency graph (includes root directory files, independent of module scan granularity) with three edge types: Python import (AST), JS/TS/Vue import/require (regex + alias resolution), cross-language route supply-demand edges (route definition × literal reference, bidirectional); cached via file_imports.json + file_routes.json, only changed/cache-missing files are re-parsed; added or deleted files are structural changes, trigger a full re-parse once to prevent missing edges. From v2, snapshot covers .py/.ts/.tsx/.js/.jsx/.vue/.sql/.yaml/.yml; v1 snapshots auto-migrated
4. Starting from changed business files, traverse reverse import edges via BFS → impact closure (changed files + all transitive dependents); test files serve only as sink nodes, do not propagate
5. Test selection: selected = test files within the closure ∪ self-changed test files; mark untested_changes (changed business files in the closure with zero tests)
6. If coverage-tiers.json exists at project root, annotate each changed file with its tier based on the longest prefix match
7. Output <project-path>/archmap/diff_impact.json; line-level snapshot is not updated in diff mode (ensuring stable results across repeated comparisons within the same work period), updated on the next full/sync run
8. Auto-stamp on change: append to diff_history.jsonl (machine-readable, with notes) and re-render 10_change_history.md (timestamp + modification content + changed file ranges + closure + test selection); no-change runs produce no record

Output structure:

{
  "changed_files": [{"path": "ui/main_window.py", "change_type": "modified", "tier": "P2", "changed_ranges": [[169, 182]]}],
  "deleted_files": [],
  "affected_closure": {"files": ["..."], "changed": ["..."], "propagated": ["..."]},
  "test_selection": {"selected": ["tests/test_main_window.py"], "skipped": ["..."], "untested_changes": []},
  "stats": {"changed_files": 1, "changed_ranges": 1, "closure_files": 3, "tests_selected": 1, "tests_skipped": 7},
  "history_path": "<project-path>/archmap/diff_history.jsonl",
  "history_doc": "<project-path>/archmap/10_change_history.md"
}

Downstream consumption: whitebox-coverage incremental mode uses diff_impact.json as the sole scope basis (selective execution + --diff-scope gap filtering + diff_gate gating); the review process uses 10_change_history.md as the change ledger input.

Mode G: Lite Minimal Incremental (auto-entered on zero-param call with existing baseline, or explicit lite, Added 2026-08-12)

Default mode for daily development iterations. Difference from sync: does not regenerate full reports 01~09 or architecture diagrams, only closes the change loop, completes in seconds:

1. Line-level snapshot comparison detects changes (same engine as Mode F, git-independent)
2. Only re-parse changed modules and merge back into the baseline (full_index / vector_cache / module_hashes / line-level snapshot / import graph cache all refreshed)
3. Auto-stamp on change: append to diff_history.jsonl + re-render 10_change_history.md (can include modification notes)
4. ETL projects auto-refresh etl_rules/ artifacts; if unverified predictions exist, perform recall validation as usual
5. Output/refresh diff_impact.json (includes direct_dependents first-level dependency summary + full transitive closure; machine-readable full closure does not occupy Agent context)

On zero change, directly returns "No changes, no update needed." For reports 01~09 reflecting the latest code, run sync or full.

Underlying Invocation

Wrapper script location:

/Users/xujin/.agents/skills/archmap/archmap <project-path> [requirement text]

Equivalent to:

# Full
python3 /Users/xujin/.agents/skills/archmap/archmap /path/to/project

# Incremental
python3 /Users/xujin/.agents/skills/archmap/archmap /path/to/project "New user reward system"

The engine package archmap_agent is self-contained and distributed with the skill (same directory as the wrapper script); no separate engine installation is required.

Constraints

• Does not start any web service.
• Does not read or write SQLite task tables.
• All state is stored in the archmap/ folder within the project path.
• Does not modify user's original business code; performs only static source code analysis.
• Full mode only scans business directories, automatically filtering test, node_modules, dist, build, etc.
• Incremental mode reuses existing baseline assets, does not re-parse unchanged modules, significantly reducing token consumption.
• All outputs are plain text JSON/YAML/Markdown/Mermaid; no images are generated.