Explore agent-directives integration as scoped runtime instructions

[pertrai1-bot]

Summary

Explore integrating agent-directives into ai-coding-agent as a runtime control surface for scoped agent behavior: adaptive workflow loading, directive/skill commands, context handoff, verification, and observability.

The goal is not to prepend the whole directive library to every request. The high-value path is selective loading: resolve a task or command to the minimum useful directive/skill files, inject those into the current task/session, and record a compact trace of what was loaded.

Motivation

ai-coding-agent already has the right primitives for this direction:

• project context/config loading
• REPL commands
• plan mode
• token tracking and context compression
• session persistence
• tool execution

agent-directives could provide a portable instruction library on top of those primitives, making this repo a reference implementation for provider-agnostic agent workflow control.

Proposed Use Cases

1. Adaptive directive loading

Add a directive loader/router that can start from a small routing instruction and load only the relevant files for the task.

Examples:

• docs-only edit → Light Path + minimal verification
• behavior bug → Debugging/TDD/Verification
• PR review → Code Reviewer skill + Verification
• planning request → Task Framing + Implementation Task Planner

This avoids global prompt bloat while making agent behavior more disciplined.

2. Directive and skill commands

Expose directives/skills through REPL commands that temporarily shape the agent's task posture.

Possible commands:

/path light|full|debug|review|explore
/skill <name>
/directive <name>
/directives status
/directives reset

Example:

/skill code-reviewer
Review this diff for merge risk.

The command should load scoped instructions for the current task/session, not permanently mutate the agent personality.

3. Context handoff as a compaction companion

The current context compression summarizes conversation history near the token limit, but summarization is lossy. A directive-backed handoff could preserve operational state in a durable artifact such as .agents/handoff.md.

Useful handoff fields:

• current task/goal
• active workflow path
• directives/skills loaded
• files read/modified
• decisions made
• verification already run
• next step
• known risks/gaps

This turns compaction from "summarize chat" into "preserve task state."

4. Verification protocol

Use a directive-backed verification step before completion. The agent should report concrete evidence instead of merely claiming success:

• commands run
• command results
• files changed
• tests/lint/typecheck status
• known limitations or skipped checks

This is especially useful for larger edits and plan-mode-to-implementation flows.

5. Instruction observability

Track which instruction files were:

• available
• selected by the router or command
• injected into the prompt
• disclosed in the agent response

A compact routing trace could look like:

Active workflow: Debugging Path
Loaded:
- directives/codebase-navigation.md
- directives/test-driven-development.md
- directives/verification.md

This gives lightweight evidence of routing without relying only on model self-report.

6. Behavioral evals

Add scenario-style tests to verify instruction routing and command behavior:

• task maps to expected path
• only expected directives/skills are loaded
• low-risk tasks do not load the full library
• verification evidence is requested for implementation tasks
• /directives reset clears scoped instructions

7. Intent-aware adaptive routing

Adaptive routing should classify user intent separately from task shape. The same surface request can require different behavior depending on what the user wants.

Examples:

• "Look at this auth bug" could mean explain, investigate, fix, review, or plan.
• "Can you review this change?" should route to Review Path and avoid editing unless explicitly asked.
• "Figure out why this test fails" should route to Debugging/Exploration first, then implement only after root cause is identified or requested.
• "Implement this feature from the PRD" should route to Full Path.

The router should consider at least:

• intent: explain, explore/investigate, plan/spec, implement, debug/fix, review, refactor, verify, operate/release
• risk: low, medium, high
• scope: docs-only, single-file, cross-file, architecture/API, dependency/config, external side effects

The selected workflow path should be based on intent + risk + scope, not only file type or keywords. The agent should briefly disclose the inferred intent/path and avoid edits when the inferred intent is review, exploration, explanation, or planning.

If a manually selected command conflicts with the user's later intent, the agent should route or warn rather than silently continuing with the wrong posture. Example:

Selected skill code-reviewer conflicts with implementation intent.
Switching to Debugging Path unless you want review-only feedback.

Design Constraints

• Do not load the entire agent-directives library by default.
• Keep activations scoped: once-per-task or session-scoped, with reset/status commands.
• Prefer task posture over theatrical personality changes.
• Do not let a manually selected skill silently mismatch the user's actual task; route or warn when needed.
• Keep the base prompt small.
• Make routing observable with file paths and a short active-path disclosure.

Possible Implementation Plan

1. Add a directive registry/manifest format for available directive and skill files.
2. Add a loader that reads selected markdown files and injects them into the agent prompt/context.
3. Add REPL commands for /path, /skill, /directive, /directives status, and /directives reset.
4. Add routing trace state to the session.
5. Add optional handoff writing/reading for long-running tasks.
6. Add intent classification to routing so user intent, risk, and scope determine the selected path.
7. Add tests for command parsing, directive loading, intent-aware routing, scoping/reset behavior, and routing trace output.

Open Questions

• Should agent-directives be vendored, referenced as a git submodule, installed from npm, or configured by local path?
• Should commands be task-scoped by default, session-scoped by default, or explicit via flags like --once and --session?
• Should adaptive routing be model-driven, rules-driven, or hybrid?
• How should directive injection interact with existing project context and AGENTS.md loading?

[coderabbitai]

🔗 Related PRs

#2 - feat: Add plan-mode switch that disables mutating tools [merged]
#3 - feat: Add model switching inside an active session [merged]
#4 - feat: model switching and plan mode (Steps 7-8) [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!