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": "<absolute or relative>" } ] }.
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 <path> 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/<id> link and/or a claude_design MCP mention — invoke the claude-design-import skill to fetch and materialize the design project to <workspace>/.architect-team/claude-design/<project-id>/, 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 <codebase>/docs/CODEBASE_MAP.md last_mapped (YAML frontmatter).
• Run git -C <codebase> 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:

{
  "codebase_path": "<absolute-path>",
  "classification": "<frontend|backend|fullstack|library|infra|data-pipeline>",
  "output_path": "<codebase>/docs/CODEBASE_MAP.md",
  "produce_route_map": true,  // or false for non-frontend classifications
  "route_map_output_path": "<codebase>/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 <codebase>/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 "<review prompt>" --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:

   { "status": "ok" | "deficient",
     "deficiencies": [
       { "map": "codebase" | "route", "section": "<heading>", "gap": "<what's missing>",
         "evidence": "<file:line or symbol the reviewer found that isn't reflected>" }
     ] }
   

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), <workspace>/docs/INTEGRATION_MAP.md, and $REQ_DIR — and writes <codebase>/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: <ISO 8601 UTC>, 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:

{
  "output_kind": "integration-map",
  "output_path": "<workspace>/docs/INTEGRATION_MAP.md",
  "codebase_inputs": ["<absolute-path-to-codebase-1>", "<...>"],
  "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 "<synthesis prompt>" --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 <codebase>/docs/CODEBASE_MAP.md.
   • Every <codebase>/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 <workspace>/.architect-team/integration-drafts/<agent-N>.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 <workspace>/docs/INTEGRATION_MAP.md with:
   • YAML frontmatter: last_synthesized: <ISO 8601 UTC>, codebases: [<names>], source_drafts: [<paths>].
   • 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:

<workspace>/.architect-team/intake-state.json:

{
  "schema_version": 1,
  "completed_at": "<ISO 8601 UTC>",
  "codebases": [
    {
      "name": "api",
      "path": "/abs/path/to/api",
      "head_sha": "<git rev-parse HEAD>",
      "head_commit_time": "<git log -1 --format=%cI>",
      "codebase_map_last_mapped": "<from frontmatter>",
      "route_map_last_routed": "<from frontmatter or null>"
    }
  ],
  "integration_map_last_synthesized": "<from frontmatter>"
}

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