docs: revamp README to clarify purpose and CLI usage#10
Merged
Conversation
Clarify project scope and replace "educational" wording with a concise description of the framework's role in building agentic systems. Reorganize README sections for a faster onboarding flow: "What is this?", "Quick Start", "Available Agents", "CLI Reference", and "Developer Agent". Highlight key features (decorator-based agent registration, LangGraph pattern, MCP permissions, multi-language code tools, safe file editing), and add a concise agents table summarizing purposes, MCP access and tools. Streamline Quick Start commands (install, test, list, info, run, timeout, verbose) and replace project-specific uv invocations with --directory so examples run from outside the repo. Remove outdated Docker instructions and old verbose featured-agent lists. These changes make the README more actionable for new users and surface important capabilities and CLI usage up front.
Update AGENTS.md to enforce `uv` as the sole package manager, expand instructions for using `uv`, and add a clear "UV IS MANDATORY" section with commands and forbidden examples. Prefer Docker for running and testing the framework: add a "DOCKER (PREFERRED)" section describing benefits and common commands, and emphasize avoiding local dependency installs. Rework Working Directory guidance to explain the project layout (agentic-framework/ is a subdirectory) and show running make from the parent directory or using `cd .. && make check`. Other tidy-ups: - Replace absolute paths with relative project paths for tests and working-directory examples. - Add NEVER rules forbidding pip, pipenv, poetry, and local installs when Docker is available. - Remove bypass-push hook instructions to encourage fixing issues. These changes improve onboarding clarity, enforce consistent dependency management, and reduce local environment drift by promoting Docker.
jeancsil
force-pushed
the
agents-and-docs
branch
from
8981738 to
59ee970
Compare
- Add requirement in AGENTS.md to update README.md when public API, agents, tools, MCP servers, or agent capabilities change. Clarify do/don't checklist to prevent stale docs. - Expand README.md with Docker quick start and rationale, example commands for building, running, and viewing logs, and note Docker as recommended workflow. - Improve local installation instructions and clearly separate Python vs system dependencies. - Revise agent usage examples for both Docker and local setups and simplify developer-agent invocation. - Add Available Tools and Available MCP Servers tables with tool/ server descriptions and input formats; detail recommended file-edit operations (search_replace and line-based formats). - Reorganize sections (quick start, tools, MCP servers, CLI reference, developer agent) for clearer navigation and synchronized guidance. Reason: ensure documentation is complete, consistent, and aligned with framework changes so contributors and users can run and extend agents reliably and avoid outdated README contents.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Clarify project scope and replace "educational" wording with a concise
description of the framework's role in building agentic systems.
Reorganize README sections for a faster onboarding flow: "What is this?",
"Quick Start", "Available Agents", "CLI Reference", and "Developer Agent".
Highlight key features (decorator-based agent registration, LangGraph
pattern, MCP permissions, multi-language code tools, safe file editing),
and add a concise agents table summarizing purposes, MCP access and tools.
Streamline Quick Start commands (install, test, list, info, run, timeout,
verbose) and replace project-specific uv invocations with --directory so
examples run from outside the repo. Remove outdated Docker instructions and
old verbose featured-agent lists.
These changes make the README more actionable for new users and surface
important capabilities and CLI usage up front.