agent-runway

Agent Runway

A Claude Code plugin that gives subagents architectural awareness before they write code.

The Problem

When Claude Code delegates work to subagents, those agents operate in complete isolation. They receive no CLAUDE.md rules, no memory, no understanding of your project structure. A subagent asked to "reduce complexity in the router" will happily extract helpers inline instead of moving them to your helpers/ module. It will add comments to "explain" its changes. It will slap # noqa on a linting error instead of fixing it.

The Fix

Agent Runway works in two layers:

1. Prevention: Intercepts every subagent spawn and injects your project's architectural context into its prompt. The subagent knows your module boundaries before writing a single line.
2. Correction: Validates every file write and tells the agent to fix violations. The agent self-corrects without human intervention.

Install it, forget about it, and your subagents stop creating tech debt.

What Happens

On session start, the plugin scans your project: directory structure, module purposes, CLAUDE.md rules. It caches this as an architectural map.

When Claude spawns a subagent, the plugin intercepts the Agent tool call and prepends the map to the subagent's prompt via updatedInput. The subagent now knows which directories exist, what each is for, what's forbidden where, and your project's rules.

This is what a subagent sees before its task:

=== AGENT RUNWAY: ARCHITECTURAL CONTEXT ===

Project: my-project

Module Boundaries:
- routers/ -> HTTP route/endpoint definitions. NO: helper functions, business logic
- services/ -> Business logic and orchestration. NO: route definitions
- helpers/ -> Shared utility/helper functions
- tests/ -> Test suite. NO: production code

Mandatory Conventions:
- NO INLINE COMMENTS [warn]
- NO LINT SUPPRESSIONS [warn]
- NO HELPERS IN ROUTERS [warn]

CLAUDE.md Rules (MANDATORY):
- DO NOT LEAVE ANY COMMENTS IN THE CODE
- ASK QUESTIONS BEFORE YOU DO ANYTHING

=== END ARCHITECTURAL CONTEXT ===

[original task prompt follows]

No extra tokens in your main conversation. No agent definitions to modify. It just works.

Installation

From GitHub

/plugin marketplace add rennf93/agent-runway
/plugin install agent-runway@rennf93

Local development

claude --plugin-dir /path/to/agent-runway

Zero Config Required

Agent Runway works out of the box. It auto-discovers your project structure by matching directory names against 25+ known patterns (routers/, services/, helpers/, models/, tests/, middleware/, adapters/, etc.) and infers purpose for unknown directories by sampling code files. It extracts imperative rules from your CLAUDE.md automatically.

No .agent-runway.yml needed unless you want explicit control.

Self-correction

The pre-flight injection prevents most violations — subagents that know the architecture write code in the right place. But when something slips through, Agent Runway catches it and tells the agent to fix it.

After every Write/Edit, two validators run:

• Convention validator: Catches comments, lint suppressions, and custom patterns across 13 languages
• Placement validator: Catches code written in the wrong module (helpers in routers, business logic in controllers)

When a violation is found, the agent receives a directive like:

[Agent Runway] You wrote code with convention violations in routers/users.py. Fix these before moving on:
  - L6: # Helper function to format user data
  - L19: Lint suppression (noqa): if "@" not in email:  # noqa: E712
Edit routers/users.py to resolve these violations, then continue with your task.

This is injected as additionalContext — Claude treats it as an instruction, not a suggestion. The agent fixes the issue and continues. No human intervention needed.

All rules are enabled in warn mode by default. The edit is never blocked — the agent self-corrects. Block mode (hard rejection of the edit) is available but disabled by default:

conventions:
  no_inline_comments:
    enabled: true
    enforcement: block

Supported Languages