docs: split AGENTS.md into separate documents#14
Merged
Conversation
timzsu
force-pushed
the
zsu/agents-polish
branch
2 times, most recently
from
d71230f to
d194263
Compare
timzsu
changed the title
timzsu
changed the title
timzsu
changed the title
…API / SDK / CLI / EXECUTORS / WORKFLOWS / ENV / PLUGINS The previous AGENTS.md was 704 lines and inlined every concern at once. Restructure as a thin routing doc that points to dedicated documents: - docs/ARCHITECTURE.md — workspace layout, topology, components, communication, object IDs, task state machine, directory map, runtime behavior (task merge, stage stickiness, context reuse, Redis control + telemetry + log channels). - docs/CODE_STYLE.md — Python rules, docstring rules, bandit rules + nosec policy, pip-audit policy + GHSA ignore list. - docs/API.md — common server REST endpoints + cursor pagination. - docs/SDK.md — sync (FlowMesh) and async (AsyncFlowMesh) clients. - docs/CLI.md — flowmesh command groups, common workflows, local stack lifecycle. - docs/EXECUTORS.md — taskType → Executor registry table; AgentExecutor env requirements (UTU_LLM_*, SERPER_API_KEY, JINA_API_KEY). - docs/WORKFLOWS.md — workflow YAML format hierarchy: single task, multi-stage DAG, graph DAG, schedule hints. - docs/ENV.md — curated server / worker / supervisor env var tables. - docs/PLUGINS.md — IdentityProvider / SubmissionGuard / UsageSink hook contract, loader semantics, worked example. - CONTRIBUTING.md — gains the commit + PR title conventions section. - AGENTS.md — 79 lines: brief project intro, pointers to all of the above plus templates/, a Reminders cheat sheet for the rules that come up most often, and a dev-workflow snippet. Adds a `docs:` PR title type to ``scripts/ci/check_pr_title.py`` and configures the heavy CI workflows (lint-typecheck, unit-tests, security, env-examples, requirements-sync) with ``paths-ignore: ['**.md', 'docs/**']`` so doc-only PRs skip code CI. Only the title-check and DCO-signoff workflows run on a pure docs PR. Signed-off-by: Zhengyuan Su <su.zhengyuan@u.nus.edu>
timzsu
changed the title
kaiitunnz
requested changes
May 4, 2026
Collaborator
kaiitunnz
left a comment
kaiitunnz
left a comment
There was a problem hiding this comment.
Leave some comments. PTAL.
Co-authored-by: Codex <codex@openai.com> Signed-off-by: Zhengyuan Su <su.zhengyuan@u.nus.edu>
timzsu
changed the title
Signed-off-by: Zhengyuan Su <su.zhengyuan@u.nus.edu>
kaiitunnz
requested changes
May 4, 2026
Signed-off-by: Zhengyuan Su <su.zhengyuan@u.nus.edu>
timzsu
force-pushed
the
zsu/agents-polish
branch
3 times, most recently
from
0a5d2c8 to
f543fd1
Compare
The previous routing list mixed Claude Code @-imports (``@docs/ARCHITECTURE.md``, ``@docs/CODE_STYLE.md``, ``@CONTRIBUTING.md``) with normal markdown links. Each @-import is inlined into the loaded context at parse time, which broke the bullet structure of "Where to read what": the trailing description text dangled after a fully-inlined multi-section file, and only three of ten docs were auto-loaded. Convert all "Where to read what" entries to plain markdown links so the section is a clean router, and add an "Auto-loaded references" section at the end of the doc that holds the three @-imports on their own lines. Same eager-load behavior, no structural damage. Signed-off-by: Zhengyuan Su <su.zhengyuan@u.nus.edu>
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
2 participants
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.
Purpose
AGENTS.mdhad grown into a monolithic agent guide that mixed routing, architecture, style rules, API notes, SDK/CLI examples, executor details, environment tables, and plugin examples. That made every agent session load a large amount of context even when only one area was relevant.This PR turns
AGENTS.mdinto a compact routing document and moves the long-form reference material into focused docs. It also addsdocs:as an allowed PR title type and configures heavy CI jobs to skip doc-only changes.Changes
AGENTS.md@imports for architecture, code style, and contributing guidance; optional links for API, SDK, CLI, executors, workflows, env, and plugins; short reminders only.docs/ARCHITECTURE.mddocs/CODE_STYLE.md# nosecpolicy, and pip-audit policy with current GHSA ignore rationale.docs/API.mddocs/SDK.mddocs/CLI.mdflowmeshcommand groups, common workflow/log/result/trace commands, local stack lifecycle, and SSH tasks.docs/EXECUTORS.mdtaskType -> Executorregistry table, executor utility locations, andAgentExecutorenvironment requirements.docs/WORKFLOWS.mddocs/ENV.mddocs/PLUGINS.mdCONTRIBUTING.mddocs:PR type and CI skipscripts/ci/check_pr_title.pynow acceptsdocs:PR titles..github/workflows/{lint-typecheck,unit-tests,security,env-examples,requirements-sync}.ymlnow usepaths-ignorefor Markdown / docs-only changes.docs:PR that changes non-doc files stillruns the relevant CI jobs.
Test plan
Documentation-focused change. Commit hooks ran successfully on the doc commits.
Pre-submission Checklist
uv run pytest tests/passes locally. N/A — no runtime code changed.[BREAKING]. Not breaking.