Runway Compass

• 

  Coach confirms the previous answer, then goes on to the next question.

• 

  The coach takes notes about the learner's study pattern (learner profile).

• 

  Architecture diagram

Inspiration

As someone who tries to stay on top of developments across several technical areas, I often hit the same friction whenever I pick up a new skill or start a personal project. It's hard to decide what to read and in what order, and to judge how to split the topic into parts that fit comfortably into an evening desk session or a weekend afternoon coffee break. Also, it's hard to pick the thread back up after a week or two.

What I found is that simple chat sessions don't help offset this effort, because a chat session doesn't "understand" how often I touch a given subject, how I prefer consuming knowledge, or which sources work better for my study habits.

This is my take on an agentic tool: an agent that does the planning and prep while I'm away, then teaches (guides) when I show up.

What it does

Runway Compass turns a goal - "get comfortable with Python for web service work" - into an ordered board of sized tasks, researches the material for each one, and then works through them with you in a Socratic way.

• Plans the whole project from one sentence. A parallel research pipeline proposes sized, prerequisite-linked tasks, filters them against what's already on your board and what they've already finished, and shows the plan before anything is written.
• Two agents, deliberately separated. A project coach owns the board. A task teacher owns one task's checklist and has no tool that could put new work on the board instead of in front of you.
• Keeps a learner model across sessions and adapts its pacing and guidance style to it. You can read, edit, and reset everything it believes about them in Settings.
• Researches while you're away — articles, duration-checked videos, exercises it writes itself — and reports what changed with one-press undo. It skips any project you are currently working in - nothing should get moved or rewritten under you while you're about to start the next task.

How I built it

Gemini 3.7 Flash on Vertex AI, Google ADK, and one Cloud Run service.

The roadmap pipeline is an ADK Workflow: research_planner splits the goal into 3-5 sub-topics; a parallel_worker fan-out researches each one concurrently in its own clean context, every branch driving its own tool loop over web search, URL fetch, and a duration-filtered YouTube lookup; two deterministic nodes thread the run's attachments into the branches and zip the results back out; then task_proposer groups the findings into sized tasks and plan_tailor orders and filters them against the board before making the pipeline's single write.

Every change the agents make is a Gemini function call landing in the same service layer the UI's own buttons call, so the agent and the REST API can't diverge. State is Firestore - domain data plus ADK's own session and memory stores - through subclasses of ADK's shipped Firestore services. Long runs are queued through Cloud Tasks, so a run survives the tab closing and resumes across instances. Terraform provisions everything; GitHub Actions deploys on merge via Workload Identity Federation, with no service account keys anywhere.

Coding assistants: Claude Code (Sonnet 5) and OpenCode (Gemini 3.7 Flash). The application itself calls Gemini 3.7 Flash through Vertex AI.

Challenges I ran into

• Failures caused by Vertex AI inference rate limits. One notable challenge I ran into during development was that my service suddenly started hitting an API limit 429 RESOURCE_EXHAUSTED. My initial attempt to mitigate this was to throttle parallel topic_researcher agents with before_model_call hooks, ensuring there's only one in-flight request at a time. That turned out to be insufficient because of Vertex AI's model-specific limits on input tokens per minute, and limiting concurrency is not the same as limiting token rate. The (mostly) full solution was to implement a shared rate limiter in front of all model calls from the service, not just the autonomous one I did at first. Additionally, I reduced the topic_researcher agent's effort level to "low."

• ADK's Workflow edges are a sequential chain - each node's output becomes the next node's input. I put a node between the planner and the fan-out, and it silently became the fan-out's input, collapsing 3-5 parallel research branches into one. No error at construction time, and every test still passed. Only carefully checking the "troubleshooting" view helped to reveal the issue.

Accomplishments that I'm proud of

• Restructuring the ADK workflow so each stage sees only what it should. task_proposer, which groups the combined research into tasks, gets a rewritten brief with the your total time budget removed — so it sizes each task against a single sitting instead of quietly trimming the plan to fit a total it was never supposed to know. plan_tailor, the last node, sees the original brief and the full conversation, because deciding whether the plan fits that total is its job. The information is withheld structurally, not requested politely in a prompt.

• Splitting project_coach and task_teacher so each has authority over its own part of the hierarchy. The task teacher owns one task's checklist and has no tool that could put new work on the board — so the agent guiding you through a task cannot wander off and rearrange the project around you.

• The whole stack rebuilds from nothing. terraform apply provisions Cloud Run, Firestore, both buckets, the scheduler and queue, Identity Platform, and the blocking function; two documented steps need a human. Merging to main builds and deploys through Workload Identity Federation, with no service account keys anywhere.

What I learned

One thing I noticed with agents is that they often take the path of least resistance while adhering to the required schema by setting all required fields and skipping optional ones. So, the project_coach agent often skips including relevant files from the intake conversations in the brief document and the research pipeline. An easy fix is to give the agent a single "nag" in a tool response, which "reminds" the model that there were files earlier in the conversation that could be relevant. This fixes the issue in most cases. I also believe this consistency is achievable through better-formulated model instructions.

What's next for Runway Compass

There are some improvements I can think of that Runway Compass could benefit from; some of which were planned from the design stage (before any code was written), and others became apparent during the development:

• Improve coaching quality: refine instructions, clean up agent tools, add TTS/STT, add spaced-repetition practice (decided by an autonomous review agent), and let users restart sessions cleanly.
• Technical improvements: split the single backend service into multiple services based on potential scalability requirements, observability, and better recovery from failed workflow runs (currently, if a run fails, topic_researchers start over even if they finished their part in the failed run).

Built With

• cloud-run
• fastapi
• firestore
• gemini
• github-actions
• google-adk
• google-cloud
• google-identity-platform
• python
• react
• tailwindcss
• terraform
• typescript
• vertex-ai
• websockets
• zustand