Skip to main content
Browse documentation
REPOTOIRE / DOCSCODE. CONTEXT. EXECUTION.

A FIELD GUIDE TO REPOTOIRE

From your goal to verified work.

Follow a goal from an agreed plan to checked results. A small shop example explains the code graph and every stage along the way.

CURRENT / V1

Current v1 runs one instruction at a time. Today’s context and impact tools supply code facts. Parallel execution and higher verified throughput remain goals to prove.

  1. 01Break down the task
  2. 02Goal Program
  3. 03ISA executable
  4. 04APU running
  5. 05Retirement

THE FOUNDATION / CODE EVIDENCE

What is Repotoire?

RepoToire is building a processor for coding agents: turn an agreed goal into instructions, run work within explicit limits, and check the results. The aim is less guesswork about facts the code can answer, with people retaining judgment and approval.

CodebaseView is a snapshot of code and its relationships from one capture. Context shows what a piece of code uses; impact shows what uses it. Symbol FS presents that evidence as readable files. Explore the example below.

CODEBASEVIEW / CODE AND RELATIONSHIPSIllustrative shop example

Which code does a total change affect?

Imagine adding a $5 shipping fee to order totals. A function is a named piece of code that does a job. These five functions show where to look.

Explore the code evidence

means “A calls B”: A uses B to do its job.

Code that uses the total

Show checkoutshowCheckout
Save an ordersaveOrder
FUNCTION WE’RE CHANGINGCalculate order totalcalculateTotal
Add item pricesitemSubtotal
Get shipping feeshippingCost

Helpers used to calculate the total

Read downward. Checkout and saved orders use the total. The total uses item prices and shipping. A change can affect both users.

Context: what does this function use? Inspect the item-price and shipping helpers to understand how the total is calculated.

Impact: what uses this function? Check checkout and saved orders after changing the total. A call relationship identifies a possible effect, not proof of a bug.

Symbol = named code, such as a function. FS = filesystem. Symbol FS presents the same code evidence as files an agent can read.

CODEBASEVIEWCapture code and its relationships

Keep the function’s code and the calls around it tied to the same source capture.

Group the evidence by function

calculateTotal / example folder

source
The function’s codeRead how it calculates the order total.
context
What the function usesItem-price and shipping helpers.
impact
What uses the functionCheckout display and saved orders.

The folder and contents above are simplified for this example. The local worker integration illustrated here requires Linux and the symbol-filesystem feature.

Fictional shop example, not a scan of your repository. Real code can contain more relationships; missing or unresolved calls limit what the graph can tell you.Symbol FS illustration. These are readable views of captured evidence; no filesystem is mounted on this page.
  1. 01

    Break down the task

    One goal. A lot of moving parts.

    Start with what you want to build, improve, or repair. Divide it into tasks with explicit limits on what may be read or changed. Each task should serve the same outcome.

    ILLUSTRATIVE SHOP EXAMPLE

    YOUR GOALInclude $5 shipping in order totals

    The checkout display and saved order should agree.

    split into
    01Inspect both users of the total

    Find the checkout display and saved-order code.

    02Update the total calculation

    Include the shipping fee within the agreed files.

    03Check both totals

    $40 of items + $5 shipping should give $45.

    The branches group tasks under one goal. Current v1 instructions run in sequence.

    Keep the outcome visible: what should be better when the work is done?

  2. 02

    Goal Program

    Agree on what done means.

    The Goal Program is the plan you review: what should change, what stays outside the task, what proves success, and which code may be touched. It records your intent and the tasks needed to pursue it.

    GOAL PROGRAM / THE AGREED PLANSHOP EXAMPLE
    Outcome
    Both checkout and saved orders include the $5 shipping fee.
    Non-goals
    Leave payment processing and tax rules unchanged.
    Success criteria
    For $40 of items, both totals are $45. The required checks pass.
    Targets
    The total calculation and its tests, within agreed file limits.
    This example makes “done” testable before work begins. Goal approval and execution approval are separate decisions.

    Approving the goal does not authorize execution.

  3. 03

    ISA executable

    Compile intent into instructions.

    ISA means instruction set architecture: the operations the runtime understands. The compiler turns your plan, current code evidence, and the repository’s checking commands into a validated instruction file called a MachineExecutable. If the requirements cannot be satisfied, it returns diagnostics explaining why.

    FROM AGREED INTENT TO FIXED INSTRUCTIONS

    Goal Program

    Your outcome, limits, and success criteria.

    Fresh CodebaseView

    Code and its relationships captured together.

    Verification recipes

    The repository’s commands for checking the work.

    inputs to
    COMPILERCheck and bind the plan

    Connect tasks to code targets and required checks.

    produces
    IF VALIDInstructions for execution

    MachineExecutable: the fixed instruction file you review and approve.

    IF REQUIREMENTS ARE MISSING OR INVALIDCompilation blocked

    Diagnostics explain what prevents a valid instruction file.

    Arrows show the compilation inputs and possible outputs. Execution approval applies to the exact instruction file produced.

    You approve the exact instruction file before execution. Compiling it does not authorize changes to your code.

  4. 04

    APU running

    Run the approved work within its boundaries.

    APU means Agent Processing Unit, RepoToire’s processor architecture for agent work. Machine is the runtime that carries out approved instructions. A worker is a coding agent given a task with explicit limits. Current v1 processes one instruction at a time.

    MACHINE / CURRENT V1ONE INSTRUCTION AT A TIME
    1. 01 / FETCHRead instruction

      Select the next instruction from the approved file.

    2. 02 / DECODEIdentify operation

      Read which kind of operation it requests.

    3. 03 / ISSUEDispatch work

      For an agent task, send a request with explicit limits.

    4. 04 / CHECKValidate result

      Match the returned result and required evidence to the task.

    5. 05 / RETIRERecord outcome

      Save the checked verdict in runtime state.

    Shop example: a worker is a coding agent given a limited task, such as updating the total calculation in the approved files.

    Arrows show stages of the same instruction. Execution waits when a worker or its evidence is not ready. The next instruction begins after retirement.

    The future target: ready, independent work can run ahead. Results remain provisional until the required evidence allows acceptance.

  5. 05

    Retirement

    Accept checked results toward your goal.

    Retirement means recording the checked outcome of an instruction in Machine’s runtime state. The result, required checks, and current source must match. Failed checks or evidence from old code cannot count as successful completion.

    RETIREMENT / RECORD THE CHECKED OUTCOME

    Worker result

    The proposed change to the order total.

    Required checks

    Checkout and saved-order tests both expect $45.

    Current source

    The evidence must still match the code being accepted.

    check together
    EVIDENCE CHECKDo the result, checks, and code match?

    A worker’s “done” message alone cannot prove success.

    verdict
    PASSRecord checked success

    Save the accepted outcome in Machine runtime state.

    FAILED, STALE, OR MISMATCHED EVIDENCENo successful completion

    Report the failed check or source mismatch.

    Example: $40 of items + $5 shipping = $45. Retirement records a checked outcome; committing, pushing, or deploying code requires a separate action.

    The future target is out-of-order completion with in-order verified retirement. Retirement does not commit, push, merge, or deploy your code.

YOUR NEXT STEP

Start with one goal

Use the quick start to prepare a repository and review the work with your agent. You can use context and impact independently of the APU flow.

Need access or help with onboarding? Contact the RepoToire team.