# Intake And Mapping > Use when entering Phase −1 of the architect-team pipeline, when any agent needs to consult codebase or integration maps, or when checking whether existing maps need refresh. Defines codebase discovery rules, the per-codebase ralph-loop with 3 reviewers (exit string "CODEBASE MAP COMPLETE"), frontend detection that triggers the route-mapper, and the integration ralph-loop with 3 explorers + master-synthesizer (exit string "INTEGRATION MAP COMPLETE"). Handles re-entry freshness checks against git commit timestamps. - Skill: `paulingram/intake-and-mapping` (Agent Skill) - Install (CLI): `npx skillmds@latest add paulingram/intake-and-mapping` - Raw SKILL.md: https://api.skillmd.com/api/skills/paulingram/intake-and-mapping/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: paulingram (https://skillmd.com/u/paulingram) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/paulingram/intake-and-mapping --- # Intake & Mapping The pipeline cannot reason about a codebase it has not mapped. This skill defines how the orchestrator builds, validates, and refreshes the structural knowledge it needs before any planning or implementation work begins. **Consumers.** This skill is the Phase −1 discipline for both `architect-team-pipeline` and `bug-fix-pipeline` (v0.9.22). The bug-fix pipeline's Phase B−1 reuses this skill VERBATIM — same codebase discovery, same per-codebase ralph loop with cartographer + route-mapper + 3-reviewer convergence, same map-freshness rules, same integration mapping, same MemPalace mining. A bug fix proposed against a stale map is the second-worst class of bug fix (after one proposed without replication) — so no shortcut, no abbreviated version. The freshness pre-scan applies identically to both pipelines. ## Codebase discovery Resolve the set of codebases the work will touch, in priority order: 1. `$REQ_DIR/codebases.json` — shape: `{ "codebases": [ { "name": "...", "path": "" } ] }`. 2. `codebases:` key in the YAML frontmatter of `$REQ_DIR/proposal.md` or `$REQ_DIR/design.md`. 3. Current working directory as a single codebase. 4. Ask the user. Resolve every path to an absolute path. Assert each is a git repo (`git -C rev-parse --is-inside-work-tree`). Classify each: - **frontend** — see frontend detection markers below. - **backend** — has `pyproject.toml` / `setup.py` / `requirements.txt` / `go.mod` / `pom.xml` / `Cargo.toml` / equivalent. - **fullstack** — both sets of markers in one repo (e.g., Next.js full-stack monorepo). Runs cartographer + route-mapper. - **library** — package manifest but no obvious app entry. - **infra** — Terraform / Pulumi / Helm / Kubernetes manifests as the dominant content. ## Frontend detection markers (any one is sufficient) - `package.json` with a frontend framework dep: react, vue, svelte, angular, next, nuxt, remix, solid, qwik, astro, sveltekit, gatsby, preact, expo, lit, alpinejs, htmx. - HTML files in `src/`, `public/`, or `app/`. - A routing config: `pages/`, `app/router/`, `src/routes/`, `react-router`, `vue-router`, `@angular/router`, `expo-router`, `tanstack/router`. - `index.html` as the entry. ## Claude Design offer detection (additive design-input source) When `$REQ_DIR` prose carries a Claude Design offer — a `claude.ai/design/p/` link and/or a `claude_design` MCP mention — invoke the `claude-design-import` skill to fetch and materialize the design project to `/.architect-team/claude-design//`, then treat that materialized directory as a design-input source for the rest of Phase −1 (the route-mapper's `DESIGN_MAP.md` per `design-fidelity-mapping`, and the `oracle-deriver` interactive-mockup walk). Detect the offer with `detect_claude_design_offer` from `scripts/claude_design/claude_design_import.py`. This is ADDITIVE — an additional design-input source ALONGSIDE the existing local/zip discovery, never a replacement. When no Claude Design offer is present (`detected` is false), the existing local design-input discovery proceeds unchanged. When the `claude_design` MCP is unavailable, `claude-design-import` instructs the user to connect it and run `/design-login`, and on the user declining auto-falls-back to the local/zip path so the run never dead-ends. ## Per-codebase mapping (one ralph loop per codebase, dispatched in parallel across codebases) Each codebase's mapping work is independent of every other codebase's mapping work — only the later integration mapping depends on all per-codebase maps being done. So all per-codebase mapping ralph loops are dispatched in PARALLEL via a single Agent-tool batch — one teammate per codebase. For a 1-codebase workspace this is a no-op; for a multi-codebase workspace it cuts wall-clock by a factor of the codebase count. Within each codebase's ralph loop: ### Step 1: Freshness check (short-circuit if current) - Read `/docs/CODEBASE_MAP.md` `last_mapped` (YAML frontmatter). - Run `git -C log -1 --format=%cI` (most recent commit ISO time). - Read `intake-state.json`'s `map_invalidated` array (codebases flagged as having a known-wrong map). - Mark `CURRENT` and skip remap ONLY if all three hold: the doc exists, doc-timestamp ≥ latest-commit-timestamp, AND this codebase is NOT in `map_invalidated`. - Else → remap. Cartographer auto-selects full vs update mode based on the change scope it detects. **Map invalidation (closes the wrong-but-fresh-map hole).** A timestamp newer than the last commit only proves the map is *recent* — not *correct*. If any agent later in the run discovers the map is materially wrong — a teammate finds a module the map never listed, the integration agent finds an integration the map missed, a diagnostic-researcher traces a path the map mis-described — that agent records the codebase in `intake-state.json`'s `map_invalidated` array. That flag forces the NEXT run's Step 1 to re-derive + re-review the map regardless of timestamps, so a wrong map can never silently survive on freshness alone. The flag is cleared for a codebase once its re-derived map passes the Step 3 three-reviewer loop. ### Step 2: Run cartographer-team (v3.4.0 — delegates to the new skill) As of v3.4.0, the cartographer + 3-reviewer convergence flow is encapsulated in the `cartographer-team` skill (`skills/cartographer-team/SKILL.md`). Steps 2 + 3 + the 3-reviewer loop in Step 4 are now ONE dispatch to that skill. Invoke `cartographer-team` (use the Skill tool with `skill: cartographer-team`) with: ```json { "codebase_path": "", "classification": "", "output_path": "/docs/CODEBASE_MAP.md", "produce_route_map": true, // or false for non-frontend classifications "route_map_output_path": "/docs/ROUTE_MAP.md", "frontend_read_only": false, // intake-and-mapping callers always work on the project's actual codebase "freshness_check": true, "completion_promise": "CODEBASE MAP COMPLETE" } ``` The skill body documents the full 5-phase flow internally (C1 freshness pre-check / C2 cartographer / C3 3-reviewer convergence / C4 MemPalace mine / C5 return verdict). Behavior is preserved bit-for-bit; only the implementation location moved from inline-in-this-skill-body to dispatch-the-skill. **Why delegate:** the `architect-team-pipeline` Phase 0b Branch B (greenfield API + frontend reference) needs the same cartographer + 3-reviewer pattern but with `frontend_read_only: true` and an alternate output path. Sharing one skill body means both pipelines run identical code paths. ### Step 3: If frontend, route-mapper runs inside cartographer-team `cartographer-team` produces `ROUTE_MAP.md` for frontend / fullstack classifications when `produce_route_map: true`. Same skill, same convergence pattern, same output location. The route-mapper additionally produces `/docs/DESIGN_MAP.md` per the `design-fidelity-mapping` skill IF AND ONLY IF design inputs exist (screenshots/Figma in `$REQ_DIR`, design tokens / Storybook / assets in the codebase). The codebase-map-reviewers MUST NOT flag the absence of DESIGN_MAP.md when no design inputs exist — it is intentionally conditional. When design inputs DO exist, all three docs (CODEBASE_MAP, ROUTE_MAP, DESIGN_MAP) are reviewed together by the 3-reviewer ralph loop. ### Step 4: Review ralph loop (exit string "CODEBASE MAP COMPLETE") Wrap the review in: ``` /ralph-loop "" --completion-promise "CODEBASE MAP COMPLETE" ``` The loop runs until the completion-promise is satisfied (all 3 reviewers return `ok`); no iteration cap (per `common-pipeline-conventions` `## Unbounded solving discipline`). Where the review prompt instructs the orchestrator to: 1. Spawn 3 `codebase-map-reviewer` agents IN PARALLEL (single message, multiple Task tool calls). Each receives: - The codebase root path. - `CODEBASE_MAP.md` (and `ROUTE_MAP.md` if present). - The minimum-completeness rubric (every directory ≥1 doc line; every entry point named; every public API of every top-level module covered; for ROUTE_MAP: every route, every dynamic param, every navigation edge, every API endpoint). 2. Each reviewer returns: ```json { "status": "ok" | "deficient", "deficiencies": [ { "map": "codebase" | "route", "section": "", "gap": "", "evidence": "" } ] } ``` 3. If all 3 return `status == "ok"` → emit the exact line `CODEBASE MAP COMPLETE` (this triggers the ralph-loop completion promise and exits). 4. Otherwise: aggregate the deficiencies (deduplicate, sort by `map` then `section`), dispatch a targeted update request: - For `map: codebase` deficiencies → re-trigger cartographer in update mode, naming the deficient sections. - For `map: route` deficiencies → re-trigger route-mapper with the deficient routes/sections. 5. Loop until the completion-promise fires. There is no iteration cap — the loop drives on convergence (all 3 reviewers `ok`), not a count. If the map genuinely cannot converge because a required input only the owner can supply is missing (e.g. an inaccessible private dependency the reviewers cannot read), surface that specific required input to the owner — loudly, while continuing all other work — and resume once it is provided. The loop never halts on iteration count. ## Phase −1D — Interaction intuition (per-frontend-codebase production + bulk-verify gate) > **Nomenclature note.** In this skill, Phase −1D is presented as its own H2 section (the focus here is the per-codebase mapping flow's late steps). In `architect-team-pipeline/SKILL.md`'s `## Phase −1 — Intake & Mapping` super-section, Phase −1D appears as sub-section D under that single H2 (the focus there is the entire pipeline). Both refer to the same orchestration step with the identical canonical name "Phase −1D"; the structural-level difference is an aesthetic choice (focus follows nesting). Tests assert the identifier "Phase −1D" appears in both files; the H2/H3 distinction is intentional. After every codebase has a complete map AND `INTEGRATION_MAP.md` is synthesized (next section), Phase −1D runs once per frontend codebase to cross-walk routes × design × integration into an explicit per-element intuition of "what action does this control take and which endpoint does it call". When no frontend codebase exists in scope, Phase −1D is a silent no-op. Per the `interaction-intuition` skill: 1. **Per-frontend-codebase intuiter dispatch.** For each codebase that produced a `ROUTE_MAP.md` in the per-codebase ralph loop above, dispatch the `interaction-intuiter` agent. It reads that codebase's `ROUTE_MAP.md`, its `DESIGN_MAP.md` (when present), `/docs/INTEGRATION_MAP.md`, and `$REQ_DIR` — and writes `/docs/INTERACTION_INTUITION_MAP.md` with `confirmed: false`. The per-codebase intuiter dispatches run in parallel. 2. **Auto-mine the intuition maps** to MemPalace. 3. **Bulk-verify gate.** The orchestrator gathers across every map every element with `confidence ∈ {low, unknown}` OR (`confidence == medium` AND `ambiguity_question != null`). If the gathered set is non-empty, present it to the user as a single numbered list and parse the reply per one of three formats (`all correct` / a list of incorrect item-number integers / `all incorrect`). Items the user did NOT flag are auto-`confirmed`. 4. **Drill-down round.** One targeted follow-up per flagged item — `AskUserQuestion` (4 options × 4 questions per message) when the candidate set fits; free-form otherwise. Each answer writes `user_verdict`, `confirmed_action`, `confirmed_endpoint`, and (when applicable) `correction_note` to the matching entry (keyed on `element_id`). 5. **Close.** Once every flagged item has a non-null `user_verdict`, flip each map's frontmatter to `confirmed: true` and `confirmed_at: `, re-mine each, and Phase −1D closes. Phase −1D is a domain gate, not a process gate — it fires whenever the gathered low-confidence union is non-empty, regardless of `--proposal-first`. ## Integration mapping (v3.4.0 — delegates to domain-research-team) As of v3.4.0, the integration-synthesis flow (3 researchers in parallel + round-robin convergence + master-synthesizer) is encapsulated in the `domain-research-team` skill (`skills/domain-research-team/SKILL.md`). Invoke `domain-research-team` (use the Skill tool with `skill: domain-research-team`) with: ```json { "output_kind": "integration-map", "output_path": "/docs/INTEGRATION_MAP.md", "codebase_inputs": ["", "<...>"], "doc_inputs": [], "frontend_read_only": false, "industry_hint": null, // optional "completion_promise": "INTEGRATION MAP COMPLETE" } ``` The skill body documents the full 5-phase flow internally (R1 input parsing / R2 3 researchers with outside-research mandate / R3 round-robin convergence / R4 master synthesis / R5 return verdict). **Important nuance for integration-mapping callers:** the `domain-research-team` skill's mandatory outside-research mandate is broader than the prior `integration-explorer` flow — researchers now ALSO perform industry / market / competitor research even for the integration-mapping use case. This is intentional: outside research surfaces integration patterns and cross-service contracts that the codebase alone may not reveal. The output map's frontmatter records `outside_research_citations_count` for traceability. The prior 3 `integration-explorer` agents are now invoked AS researchers by `domain-research-team` (the agent is the same; the skill wraps it). Behavior is preserved structurally — same 3-way convergence + master synthesis + confirmation pass. **Legacy inline flow (preserved for reference, no longer the active code path):** The pre-v3.4.0 inline flow ran 3 `integration-explorer` agents directly with the synthesis prompt below. That flow now runs INSIDE `domain-research-team` Phase R2. The prompt below documents the conceptual contract; the skill body documents the canonical implementation: ``` /ralph-loop "" --completion-promise "INTEGRATION MAP COMPLETE" ``` The loop runs until the completion-promise is satisfied (all 3 explorers confirm); no iteration cap (per `common-pipeline-conventions` `## Unbounded solving discipline`). Synthesis prompt (legacy reference): 1. Spawn 3 `integration-explorer` agents IN PARALLEL. Each receives: - Every `/docs/CODEBASE_MAP.md`. - Every `/docs/ROUTE_MAP.md` where present. - Read access to boundary code: HTTP clients (`requests`, `httpx`, `axios`, `fetch`), queue consumers/producers, shared schemas (protobuf, OpenAPI, GraphQL SDL), deployment configs (compose files, k8s manifests, Terraform), env files, contract files. 2. Each agent independently writes its own synthesis to `/.architect-team/integration-drafts/.md`. 3. **Round-robin convergence:** each agent reads the other 2's drafts, flags gaps, revises its own. Iterate until each agent confirms the other two's drafts each cover 100% of what their own draft covers. 4. Spawn `master-synthesizer`. It reads all 3 drafts; produces `/docs/INTEGRATION_MAP.md` with: - YAML frontmatter: `last_synthesized: `, `codebases: []`, `source_drafts: []`. - Sections: Overview, Per-Pair Integration table, Contracts/Schemas catalog, Deployment topology, Known failure modes, Open questions. 5. **Confirmation pass:** present the master doc to each of the 3 original explorers; each must reply with `confirms: true` or list discrepancies. Master-synthesizer revises until all 3 confirm. 6. When all 3 confirm → emit `INTEGRATION MAP COMPLETE`. ## Re-entry state After Phase −1 completes (or short-circuits), persist: `/.architect-team/intake-state.json`: ```json { "schema_version": 1, "completed_at": "", "codebases": [ { "name": "api", "path": "/abs/path/to/api", "head_sha": "", "head_commit_time": "", "codebase_map_last_mapped": "", "route_map_last_routed": "" } ], "integration_map_last_synthesized": "" } ``` On the NEXT invocation of `/architect-team`: 1. Re-run discovery (the codebase set may have changed). 2. For each codebase: compare current `git log -1 --format=%cI` against the persisted `head_commit_time`. If unchanged → use existing maps. If changed → re-run mapping per the per-codebase ralph loop above. 3. If any codebase map regenerated → re-run integration mapping. Else use existing `INTEGRATION_MAP.md`. 4. Update `intake-state.json` at the end. ## Anti-patterns to reject | Rationalization | Rebuttal | |---|---| | "The map is mostly right, I'll just proceed" | Mostly-right plus undetected gaps is how parallel teams produce conflicting code. The 3-reviewer ralph loop is cheap insurance. | | "Cartographer already handles freshness, we don't need our own check" | Cartographer's check is per-doc. Ours covers integration-map freshness across codebases. Both run. | | "Just one reviewer is enough" | Single reviewers miss things consistently. The 3-agent independent verdict is the whole point. | | "Skip integration mapping for single-codebase work" | Run it anyway — it generates the INTEGRATION_MAP.md the reuse-first-design skill consults. The doc may be short, but the file must exist. | | "The design-recon classified these screens UNCHANGED, so downstream agents can skip verifying them" | A Phase −1B classification of *what changed* is a re-mapping signal — it tells the mapping loop what to re-derive. It is NOT a fidelity verdict. Downstream verification (`visual-fidelity-reconciliation`, `editability-completeness`) must NEVER consume an intake "UNCHANGED" label as a reason to skip a screen — it verifies against the Oracle directly. And during a design-baseline migration "UNCHANGED" inverts entirely: an unchanged screen has not been migrated, so it is drifted. A classification answers a different question than verification — never let one stand in for the other. |