Codebase context

Codebase Context — Agent Instructions

Invocation

• /codebase-context <IDEA_ID> Where:
• IDEA_REF = $ARGUMENTS (single token; no spaces)

If missing, STOP.

Resolve IDEA_ID (required)

Before using any paths:

• Call vf.resolve_idea_id with idea_ref = $ARGUMENTS
• Store returned idea_id as IDEA_ID
• Use IDEA_ID for all paths and YAML headers

Goal

Produce a lightweight, durable “map” of the existing codebase relevant to this idea, focusing on:

• where to extend vs create
• major boundaries (API layer, core logic, models/state, UI, tests)
• any constraints/invariants implied by the current architecture

This is NOT a full survey and NOT a task list. It is an early anchor to prevent greenfield assumptions.

Canonical paths (repo-relative)

Idea root:

• docs/forge/ideas/<IDEA_ID>/

Inputs (required):

• docs/forge/ideas/<IDEA_ID>/latest/concept_summary.md
• docs/forge/ideas/<IDEA_ID>/inputs/concept_summary_config.md Fallback/optional:
• docs/forge/ideas/<IDEA_ID>/latest/idea_normalized.md
• docs/forge/ideas/<IDEA_ID>/inputs/idea.md

Outputs:

• docs/forge/ideas/<IDEA_ID>/latest/codebase_context.md
• Run snapshot:
  • docs/forge/ideas/<IDEA_ID>/runs/<RUN_ID>/outputs/codebase_context.md

Logs:

• docs/forge/ideas/<IDEA_ID>/run_log.md

Method (generic, repo-aware)

1. Read the concept summary (primary semantic anchor).
2. Identify which kinds of components are likely involved:
   • API endpoints / controllers / routers
   • core domain logic / services
   • data models / schemas / state
   • UI components
   • orchestration / simulation engine (if applicable)
   • tests and fixtures
3. Do a targeted scan of the repo to find:
   • existing entry points matching the feature area (e.g., control/admin/simulation/session/etc.)
   • existing patterns for request/response models and state persistence
   • existing “config” or “policy” mechanisms that constrain behavior
4. Capture only the minimum necessary file/module references (10–25 max):
   • keep it stable, not exhaustive
5. Write the output artifact.

If you are unsure where something lives, state it as a hypothesis + provide search cues (keywords to grep), rather than inventing file paths.

Output format: codebase_context.md

Write with YAML header + sections.

YAML header shape:

doc_type: codebase_context idea_id: "" run_id: "" generated_by: "Codebase Context" generated_at: "" sources: - "docs/forge/ideas//latest/concept_summary.md" - "docs/forge/ideas//latest/idea_normalized.md (if used)" status: "Draft"

Codebase Context

Purpose of this map

(1 short paragraph)

High-level architecture boundaries (as observed)

• Boundary: ... — responsibility — notes

Likely extension points

• Area: ... — existing component(s) — recommended extension approach

Key existing concepts to reuse

• Concept/Model: ... — where it exists — why it matters

Constraints implied by current architecture

• Constraint: ... — evidence — impact

Candidate file/module touch list (max ~25)

List as bullets with a short reason:

• — why it’s relevant

Unknowns / where to look next

• Unknown: ... — suggested keywords or search locations

Required tool calls

1. vf.start_run with idea_id= (label: codebase-context)
2. Write run snapshot to runs//outputs/codebase_context.md
3. Write latest to latest/codebase_context.md
4. Append a run_log entry with stage codebase.context and outputs.