ghostonbutterbread/appmap

AppMap

Map a local application and forge focused brainstorm specs from source/boundary/sink evidence.

Invocation

/appmap <program> <target_path> [--target-kind <kind>] [--mode baseline|focus] [--focus baseline|rce|renderer-content-trust] [--from-baseline <run_root>] [--write-specs] [--output-mode standalone|canonical] [--family <family>] [--lane <lane>] [--promote-to-brainstorm]
/appmap <program> <target_path> --research-mode local|web|hybrid [--research-query WORD [WORD ...]] [--research-seed <path>] [--research-source-url <https-url>]
/appmap <program> <target_path> --mode baseline [--electronegativity-root <controlled_run_dir>]
/appmap --list-handoffs --brainstorm-root <brainstorm_root>
/appmap --campaign-status --brainstorm-root <brainstorm_root>
/appmap --validate-handoff <promoted_spec>
/appmap --plan-handoff <promoted_spec> [--brainstorm-hypothesis H001]

Examples:

/appmap canva /home/ryushe/Shared/binaries/canva/exe/input/app_asar --target-kind electron-exe --focus rce --write-specs
/appmap canva /home/ryushe/Shared/binaries/canva/exe/input/app_asar --target-kind electron-exe --mode baseline
/appmap canva --from-baseline ~/Shared/binaries/canva/exe/appmap/<baseline-run> --focus renderer-content-trust --write-specs
/appmap canva /home/ryushe/Shared/binaries/canva/exe/input/app_asar --target-kind electron-exe --focus rce --write-specs --output-mode canonical --family binaries --lane exe
/appmap demo /path/to/source --focus rce

Required Preflight

Read the playbook before running the mapper:

1. $HARNESS_ROOT/prompts/appmap-playbook.md
2. Existing target lane notes when the family/lane is obvious
3. Existing brainstorm/spec.md only for context; do not overwrite it from AppMap

Canonical Files

• Playbook: $HARNESS_ROOT/prompts/appmap-playbook.md
• Mapper: $HARNESS_ROOT/agents/app_mapper.py
• Research module: $HARNESS_ROOT/agents/appmap_research.py
• Default output: ~/Shared/appmap/{program}/static/appmap/{run_id}/
• Canonical output: ~/Shared/{family}/{program}/{lane}/appmap/{run_id}/
• Generated specs: {output}/generated_specs/
• Agent contexts: {output}/agent_contexts/<hypothesis_id>-<candidate_id>-<agent_key>.json when generated specs link hypotheses to candidates
• Run manifest: {output}/manifest.json
• Run index: ~/Shared/{family}/{program}/{lane}/appmap/index.jsonl for canonical runs
• Baseline artifacts: {output}/baseline/records.jsonl, quality_report.json, coverage_gaps.jsonl, posture_summary.md, category_plan.json, triage_hypotheses.jsonl, and focus_recommendations.jsonl
• Noise audit artifacts: {output}/noise/filtered_surfaces.jsonl and {output}/noise/summary.json
• Electron enrichment summary: {output}/baseline/enrichments/electronegativity.json when --electronegativity-root is provided

Responsibilities

• Run static AppMap against local source or extracted application code.
• Support baseline mode as reusable pre-runtime topology/posture mapping. Baseline mode writes no focused vulnerability spec.
• Support focused overlays, including rce and renderer-content-trust, over either the current scan or an explicit --from-baseline run root.
• Preserve AppMap artifacts: profile, architecture, surfaces, flows, candidates, rejected candidates, and summary.
• Preserve baseline artifacts: stable records, relationships, quality report, coverage gaps, posture/category triage, and focus recommendations.
• Preserve filtered/noise evidence in noise/ so operators can tune the noise meter without losing discarded leads.
• Generate parser-valid brainstorm specs when --write-specs is requested and candidates exist.
• Preserve candidate-isolated agent handoff contexts with only the linked map IDs, evidence snippets/files, active packs, and next steps.
• Ensure each AppMap hypothesis links to exactly one appmap-C#### candidate and write one context packet per suggested agent.
• Write manifest.json plus appmap/index.jsonl so future modules discover AppMap artifacts without reading findings ledgers.
• Promote generated specs/context packets into brainstorm/ only when explicitly requested.
• During promotion, keep raw surfaces, flows, candidates, and rejected candidates in the AppMap run root.
• List, validate, and plan promoted handoffs with read-only CLI modes before runtime.
• Do not overwrite existing brainstorm/spec.md unless the user explicitly chooses that filename and allows overwrite.
• Keep packet active_target_packs candidate-evidence scoped so mixed targets do not leak unrelated framework context.
• Keep agent packets bounded: linked IDs, snippets, focus files, quality refs, and gap refs only. Do not pass raw AppMap JSONL or raw scanner findings into agents.
• Import controlled Electronegativity output only as bounded enrichment from structured inventory.json, hypotheses.jsonl, and electron-team-context.json. Raw findings.json stays on disk and is summarized as ignored.
• Keep research no-network-by-default. Prefer --research-mode local|web|hybrid plus --research-query WORD [WORD ...].
• Use --research-mode local for local --research-seed artifacts. Use --research-mode web for explicit online source fetches without an extra online flag. Use --research-mode hybrid to process local seeds first and then explicit web sources only when --research-online and --research-source-url are present.
• Treat --research-provider, --research-online, and --research-source-url compatibility carefully: old provider flags still work, but docs and new commands should prefer mode/query. Do not require --research-online with --research-mode web.
• Keep AppMap pre-runtime. Do not add or use zero_day_team --appmap integration from this skill.
• Hand generated specs to the normal team runtime only when the user explicitly asks to run hypotheses.

Workflow

1. Resolve program, target_path, target-kind, mode/focus, and output root.
2. Confirm target_path is a local directory. Do not run the target application.
3. For a reusable baseline/posture map, run:

cd "${HARNESS_ROOT:-$HOME/projects/bug_bounty_harness}"
PYTHONPATH="$PWD${PYTHONPATH:+:$PYTHONPATH}" \
  python3 agents/app_mapper.py <program> <target_path> \
  --target-kind auto \
  --mode baseline

With controlled Electronegativity enrichment:

python3 agents/app_mapper.py <program> <target_path> \
  --target-kind electron-exe \
  --mode baseline \
  --electronegativity-root <controlled-electronegativity-run-dir>

4. For focused RCE output, run:

cd "${HARNESS_ROOT:-$HOME/projects/bug_bounty_harness}"
PYTHONPATH="$PWD${PYTHONPATH:+:$PYTHONPATH}" \
  python3 agents/app_mapper.py <program> <target_path> \
  --target-kind auto \
  --focus rce \
  --write-specs

For a focus overlay over an existing baseline:

python3 agents/app_mapper.py <program> \
  --from-baseline <appmap-baseline-run-root> \
  --focus renderer-content-trust \
  --write-specs

For canonical lane storage:

python3 agents/app_mapper.py <program> <target_path> \
  --target-kind auto \
  --focus rce \
  --write-specs \
  --output-mode canonical \
  --family <family> \
  --lane <lane>

5. Read appmap_summary.md, architecture.md, manifest.json, baseline quality/posture artifacts, candidates.jsonl, rejected_candidates.jsonl, and generated agent_contexts/*.json when present.
6. Validate generated specs with agents.brainstorm_spec.parse_brainstorm_spec when present.
7. If research is requested, prefer --research-mode local --research-query <terms> --research-seed <path> for offline artifacts, or --research-mode web --research-query <terms> --research-source-url <https-url> for explicit online sources. Hybrid mode reads local seeds first and then fetches explicit HTTPS --research-source-url values only when --research-online is set; do not use search scraping, crawling, or target probing.
8. Promote only on request with --promote-to-brainstorm. Canonical mode defaults to {lane_root}/brainstorm; standalone mode needs --brainstorm-root.
9. For promoted specs, run --list-handoffs, --validate-handoff, or --plan-handoff as needed. These modes are read-only and must not write findings ledgers, raw map data, coverage, or reports.
10. Report the output directory, manifest/index, baseline quality/readiness, candidate count, generated specs, promoted handoff paths when any, validation counts/errors, planned runtime command, research mode/query/provider/network status, and no-candidate reasons visible in rejected candidates.

Promotion

Default promotion writes a unique per-run handoff directory:

~/Shared/{family}/{program}/{lane}/brainstorm/appmap-<run_id>-<focus>/rce-spec.md

This is --promotion-layout flat and remains the default for compatibility. Opt in to category layout with --promotion-layout category to write:

~/Shared/{family}/{program}/{lane}/brainstorm/appmap-<run_id>/<focus>/rce-spec.md

It also copies matching context packets to the spec's sibling context directory:

~/Shared/{family}/{program}/{lane}/brainstorm/appmap-<run_id>-<focus>/agent_contexts/
~/Shared/{family}/{program}/{lane}/brainstorm/appmap-<run_id>/<focus>/agent_contexts/

Promoted specs and packets keep pointers to the originating AppMap run. Existing brainstorm/spec.md remains untouched; --promote-spec-name chooses a filename inside the per-run promotion directory, and overwrite applies only there.

Runtime Handoff

AppMap stops after artifact and spec generation. If the user asks to run a generated spec, use the existing runtime explicitly:

cd "${HARNESS_ROOT:-$HOME/projects/bug_bounty_harness}"
PYTHONPATH="$PWD${PYTHONPATH:+:$PYTHONPATH}" \
  python3 agents/zero_day_team.py <program> <target_path> \
  --brainstorm-spec <appmap-output>/generated_specs/rce-spec.md \
  --brainstorm-only

For AppMap-linked specs, normal brainstorm runtime handoff consumes agent_contexts/*.json automatically. The adapter matches hypothesis_id, appmap-C#### candidate evidence, and agent_key, then uses the packet as the agent prompt context instead of the spec-wide mental model and impact primitives. Missing, duplicate, ambiguous, or multi-candidate linkage is a hard error.

Do not introduce a zero_day_team --appmap invocation here.

Validation

Promoted handoff discovery:

cd "${HARNESS_ROOT:-$HOME/projects/bug_bounty_harness}"
python3 agents/app_mapper.py --list-handoffs --brainstorm-root ~/Shared/<family>/<program>/<lane>/brainstorm

Campaign status / operator view:

cd "${HARNESS_ROOT:-$HOME/projects/bug_bounty_harness}"
python3 agents/app_mapper.py --campaign-status --brainstorm-root ~/Shared/<family>/<program>/<lane>/brainstorm

Promoted handoff validation:

python3 agents/app_mapper.py --validate-handoff <promoted-spec>

Planning prints the exact existing runtime command:

python3 agents/app_mapper.py --plan-handoff <promoted-spec> --brainstorm-hypothesis H001

The planned command must use python3 agents/zero_day_team.py <program> <target_path> --brainstorm-spec <promoted-spec> --brainstorm-only and must not include --appmap. Runtime defaults to one agent per hypothesis. If the user explicitly wants clustered execution for a reviewed AppMap campaign, pass --brainstorm-cluster-size 2 (or another small value); clustering is only for assignments sharing the same focus files, source, and sink.

cd "${HARNESS_ROOT:-$HOME/projects/bug_bounty_harness}"
python3 -m pytest agents/test_app_mapper.py -q
./sync_skills.sh --dry-run