Skills-Based Architecture With Ask/Tell API For Docent

by Admin 55 views
Skills-Based Architecture with Ask/Tell API for Docent

Hey guys, let's dive into how we can revamp Docent's architecture, making it more streamlined, intuitive, and aligned with industry best practices. We're talking about a shift to a skills-based architecture and a simplified ask/tell API paradigm. This change isn't just about making things cleaner; it's about boosting discoverability, simplifying our mental models, and setting us up for future growth. Let's break it down.

The Problem: Friction in the Current System

Right now, Docent uses a 4-tool API (start, ask, act, tell) which is a bit clunky, especially with separate concepts for runbooks and templates. This setup creates a few headaches:

  1. Discovery Dilemma: Agents (like you and me!) have to know the exact names of runbooks to use them with the act tool. It's like having to remember a secret code just to get something done. This can be a pain.
  2. API Overload: Four tools seem a bit much, doesn't it? The core of what we're doing could be a lot simpler. It's like having too many buttons on a remote control – you end up not using half of them.
  3. Missing the Mark: The current system isn't quite in sync with what's trending in the industry. For example, Anthropic's skills pattern is a cleaner way to handle things.
  4. Artificial Separation: Why treat procedural workflows (runbooks) and document creation (templates) as totally separate things? They're both just ways of getting stuff done.

The Proposed Solution: A Skills-Based Renaissance

Here’s the plan: We're moving to a skills-based architecture that's inspired by Anthropic's skills pattern. Think of it as a fresh start, making everything easier to find and use. Here's how it'll work:

1. Unified Resource Model: Skills as the Core

First things first, we'll merge runbooks and templates into a single concept: skills. We'll use a SKILL.md format for these skills, which means they'll all follow the same structure: YAML frontmatter (for metadata) and markdown instructions. These skills will be organized by domain, like git/, github/, docent/, project/, and so on. This will make it easier to find what you need.

2. Simplified API: Ask and Tell

Next, we'll simplify the API. We'll have:

  • docent:start: This will return a list of all the skills that are enabled. It's like a quick menu to see what's available.
  • docent:ask: This will be your go-to query tool. It'll search through documentation and discover the skills that apply to your query.
  • docent:tell: This is for creating documents. It’s a straightforward way to get things done.

We're saying goodbye to docent:act because skill discovery will happen through natural language in ask. This makes the whole process more intuitive.

3. Glob-Based Skill Configuration: Control at Your Fingertips

We'll use glob patterns for skill configuration. This gives users explicit control over which skill groups are enabled. Here’s an example:

# .docent/config.yaml
version: "1.0.0"
skills:
  - docent/*
  - git/*
  - github/*
  - !github/pull-request  # Opt-out with negation
  - custom/*

This .docent/config.yaml file lets you specify which skills you want to use. You can include entire groups or exclude specific ones. It's all about making sure you only have the skills you need.

4. Skill Discovery: Finding What You Need, Naturally

When you use ask, it will search both your documentation and discover the skills that match. Initially, we'll use keyword matching on skill descriptions (no fancy LLM or embeddings just yet). Skills will be grouped by directory, displayed in a hierarchical way, making it easy to browse.

5. Merge Semantics: Everything in Its Place

  • Bundled skills will live in src/skills/.
  • Local project skills will be in .docent/skills/.
  • You'll be able to override bundled skills by path (e.g., overriding git/commit).

This setup keeps everything organized and allows for customization.

6. Self-Service Migration: Upgrading Made Easy

We'll create a docent/migrate skill to handle the upgrade from the old v0.9 to the new v1.0. This skill will be:

  • Idempotent: Safe to run multiple times.
  • Converts: Runbooks into skills and templates into doc skills.
  • Updates: Your config with version tracking.

This makes the migration process smooth and user-friendly.

The Benefits: Why This Matters

So, what's the big deal? Why go through all this trouble? Here’s what you get:

  1. Simpler Mental Model: One core concept (skills) instead of three (runbooks, templates, and tools). Easier to learn and remember.
  2. Better Discovery: Natural language queries will help you find the right skills. No more guessing names.
  3. Industry Alignment: We'll be on the same page as Anthropic and other leading-edge systems.
  4. Explicit Control: You decide which skill groups to enable. No unnecessary clutter.
  5. Smaller Context: Only the skills you've opted into will be loaded, which will make things faster.
  6. Self-Documenting Migrations: The upgrade process itself will be a Docent skill. It's like a built-in guide.

Breaking Changes: Heads Up!

Of course, there will be some changes to be aware of:

  • Config Format: We're adding a version and skills fields.
  • Directory Structure: .docent/skills/ will replace runbooks/ and templates/.
  • API: act tool is going away. Discovery will happen via ask.
  • Migration Required: You'll need to migrate existing projects.

Implementation Phases: How We'll Get There

Here’s the roadmap for this transformation:

  1. Version Tracking: Add a version field to the config schema.
  2. Migration Skill: Create the self-service upgrade skill.
  3. Skill Infrastructure: Build the glob matcher, loader, and registry.
  4. Tool Refactoring: Update start, ask, tell, and deprecate act.
  5. Bundled Migration: Convert Docent’s own runbooks and templates.
  6. Bootstrap Enhancement: Smart skill selection based on project type.
  7. Testing & Docs: Create a migration guide and compatibility tests.

Open Questions: Let's Discuss

We're still figuring out a few things. Here are some open questions we need to address:

  1. Should the migration skill be named docent/migrate or docent/upgrade?
  2. Do we need advanced search (like MCP sampling) for better discovery, or will keyword matching be enough for v1.0?
  3. Should migration happen on a feature branch or directly on main with beta releases?

Next Steps: What Happens Now?

So, what’s next?

  1. Get your feedback on this approach.
  2. Write ADR-0007: Skills-Based Architecture.
  3. Create a detailed implementation plan.
  4. Start development on a feature branch.

Let’s make Docent even better, together!