agent-and-state
Skill4 starsChanged 57 days agoMITView on GitHub
Agent, prompt, tool, LLM-provider, and state-schema conventions — parse→fallback→format node pattern, frozen-dataclass defaults, serialization, schema versioning, full testing conventions. Use when modifying src/yeaboi/agent/, prompts/, tools/, sessions.py, adding/changing state fields, or writing tests.
- Reads credentials
In this repository10 other files it gives its agents.
- AGENTS.mdAGENTS.md
- babysit-prsSkill
- ci-and-releaseSkill
- development-automationSkill
- loggingSkill
- mode-blueprintsSkill
- pr-feedbackSkill
- project-mapSkill
- tui-standardsSkill
- web-frontendSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
15 rules. About 0 are common, 2 are distinctive, and 13 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
13
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 14
Every generation node follows this three-helper pattern:
- Very specific: line 26
When a generation node produces output, it sets pending_review to the node name.
- Very specific: line 40
All tools are registered via get_tools() in tools/__init__.py.
- Very specific: line 48
Create or extend a file in tools/ with @tool-decorated functions
- Very specific: line 49
Import and append to the tools list in get_tools()
- Very specific: line 58
Default models: claude-sonnet-4-6 (Anthropic), gpt-4o (OpenAI), gemini-2.5-flash (Google), us.anthropic.claude-sonnet-4-6-v1:0 (Bedrock), …
- Very specific: line 68
All other fields are optional (total=False) and populated progressively as nodes run
- Very specific: line 75
Add to ScrumState in agent/state.py
- Very specific: line 76
Add tests in test_state.py
- Very specific: line 77
Update __init__.py exports if public
- Very specific: line 78
If the field should persist across --resume, it serializes automatically (only messages is skipped)
- Very specific: line 79
If adding a field to a frozen dataclass, always provide a default value for backward compatibility with saved sessions (e.g., title: str = …
- Very specific: line 115
Use pytest fixtures for shared setup (e.g.
- Very specific: line 116
Use monkeypatch to avoid filesystem writes, network calls, and delays in tests
- Distinctive: line 117
Test both happy path and edge cases (empty input, boundary values, immutability)
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Agent, Prompt, Tool & State Conventions
Node Conventions
Nodes are plain functions in agent/nodes.py taking ScrumState and returning a dict. Key patterns:
Parse → Fallback → Format
Every generation node follows this three-helper pattern:
_parse_*_response(text)— extract JSON from LLM response, handle markdown fences_build_fallback_*()— deterministic fallback artifacts when LLM fails (no LLM call)_format_*()— Rich rendering for REPL display
Error handling
_is_llm_auth_or_billing_error(e)checks if an exception is auth/billing — these are re-raised (user must fix credentials). All other LLM errors trigger fallback artifacts and a warning log.- Rate-limit errors (429) are retried with exponential backoff in the REPL layer (
_handle_rate_limit), not in nodes.
Human-in-the-loop review
When a generation node produces output, it sets pending_review to the node name. The REPL intercepts the next user input and routes to [1] Accept [2] Edit [3] Reject. On edit, feedback is packed as "{feedback}\n\n---PREVIOUS OUTPUT---\n{serialized}" so the node can extract both the feedback and previous generation.
Prompt Conventions
Prompts live in prompts/ with a factory function per file:
get_system_prompt(),get_analyzer_prompt(questionnaire, ...),get_feature_generator_prompt(analysis), etc.- Each factory takes parameters (not the full state) and returns a string
- Prompts use the ARC framework: Ask (what to do), Requirements (constraints), Context (background)
# See docs: "..."comments cross-reference theory sections
Tool Conventions
Registration
All tools are registered via get_tools() in tools/__init__.py. This single factory function imports all tool modules and returns a flat list of BaseTool instances.
Lazy imports
Tool modules are imported inside get_tools(), not at module level. This is because tool dependencies (PyGithub, azure-devops, jira SDK) may not be installed. Lazy import means from yeaboi.tools import get_tools always succeeds; ImportError surfaces only when get_tools() is called.
Adding a new tool
- Create or extend a file in
tools/with@tool-decorated functions - Import and append to the tools list in
get_tools() - The docstring is critical — the LLM reads it to decide when to use the tool
- Set risk level via the tool's position in the graph routing (auto-execute for read, human confirmation for write)
LLM Provider Conventions
agent/llm.py provides get_llm() — a factory supporting Anthropic (default), OpenAI, Google, AWS Bedrock, Ollama (local), and the six OpenAI-wire vendors:
- Each provider is lazy-imported inside an if-branch so the module works even if optional packages aren't installed
- Provider selected via
LLM_PROVIDERenv var; model override viaLLM_MODEL - Default models:
claude-sonnet-4-6(Anthropic),gpt-4o(OpenAI),gemini-2.5-flash(Google),us.anthropic.claude-sonnet-4-6-v1:0(Bedrock),qwen3:8b(Ollama) - Install optional providers:
uv sync --extra openai/--extra google/--extra bedrock/--extra ollama src/yeaboi/llm_providers.pyis the table for every OpenAI-wire vendor (xAI/Grok, DeepSeek, Moonshot/Kimi, Mistral, Qwen, Z.ai/GLM). They all speak the OpenAI protocol at their own host, so they share oneChatOpenAI(base_url=...)branch and add no dependency — theopenaiextra covers them. Adding a seventh is a row in that table, not a branch inget_llm():_PROVIDER_DEFAULTS,_ANALYSIS_FAST_MODELS,_CLASSIFIER_MODELS, the wizard cards and the fourprovider_verification.pychains all derive from it. Each takes<VENDOR>_BASE_URLto reach a regional host or gateway.- Bedrock uses IAM credentials (no API key) — auto-detects AWS profile from
~/.aws/configviaget_aws_profile()inconfig.py. On Lightsail, uses[profile assumed]withcredential_source=Ec2InstanceMetadata. The boto3 session is created with explicit profile + increased read timeout (300s) for cross-region inference profiles. - Ollama is the keyless local provider (README: "Local Mode (Ollama)") —
OLLAMA_BASE_URL(defaulthttp://localhost:11434),OLLAMA_NUM_CTX(default 16384; the server's 2-4k default silently truncates the big planning prompts). Reliability layer:get_llm(json_mode=True)turns on ChatOllama's constrained JSON decoding (format="json", no-op for cloud providers), andinvoke_json()inagent/llm.pywraps every JSON-parsed call site (planning nodes, mode engines, team_learning) with a one-shot "your JSON was invalid, fix it" re-ask for all providers.invoke_jsoncallstrack_usage()internally — callers must not track again. Never passjson_mode=Trueon prose paths (conversational agent, llm_tools, guardrail classifier). Local failures surface via_local_llm_hint()innodes.py— the single decision point (used by_should_reraise_llm_error, the TUI's_classify_api_error, and all 4 mode engines) mapping four cases to actionable hints: langchain-ollama not installed → "uv sync --extra ollama", model not pulled (404) → "ollama pull<model>", read timeout → "try a smaller model", server down → "ollama serve". Cloud connection blips keep the graceful fallback. Prose paths strip qwen3<think>blocks viastrip_think_tags(); chat history is trimmed to the context window by_trim_history_for_local()(cut at HumanMessage boundaries only, never splits tool-call pairs);warn_if_context_overflow()logs when a prompt likely exceedsOLLAMA_NUM_CTX. The setup wizard verifies the langchain-ollama package + server + pulled model, and offers an in-app model download (pull_ollama_model()inprovider_verification.py, streamedPOST /api/pull).
State Schema Conventions
- ScrumState is a
TypedDict— this is the LangGraph convention for graph state messagesis the only required field, usingAnnotated[list[BaseMessage], add_messages]for append semantics- All other fields are optional (
total=False) and populated progressively as nodes run - Frozen dataclasses for artifacts (Feature, UserStory, Task, Sprint, ProjectAnalysis) — immutable once created, serializable via
asdict() - Mutable dataclass for QuestionnaireState — updated incrementally by the intake node
- Artifact lists use
Annotated[list[...], operator.add]so nodes can return new items that get appended
Adding new state fields
- Add to
ScrumStateinagent/state.py - Add tests in
test_state.py - Update
__init__.pyexports if public - If the field should persist across
--resume, it serializes automatically (onlymessagesis skipped) - If adding a field to a frozen dataclass, always provide a default value for backward compatibility with saved sessions (e.g.,
title: str = "",discipline: Discipline = Discipline.FULLSTACK)
Frozen dataclass backward compatibility
New fields on frozen dataclasses MUST have defaults so deserialization of old JSON doesn't fail:
# Good — old sessions without this field still deserialize
title: str = ""
discipline: Discipline = Discipline.FULLSTACK
test_plan: str = ""
# Bad — breaks --resume for sessions saved before this field existed
title: str # no default!The _dict_to_*() functions in sessions.py use .get() for optional fields so missing keys don't raise KeyError.
Session Persistence
Serialization
sessions.py handles state serialization for --resume:
messagesis the only field skipped (not needed for resume; re-initialized to[])- Custom
_StateEncoderhandles: frozen dataclasses (asdict()), enums (.value), sets (→ lists), tuples (→ lists) - Reconstruction functions:
_dict_to_analysis(),_dict_to_story(),_dict_to_task(),_dict_to_sprint(),_dict_to_questionnaire()— each handles type conversion (enum parsing, tuple reconstruction)
Schema versioning
CURRENT_SCHEMA_VERSION = 12tracked in aschema_infotable (v3=team_profiles, v4=session_mode, v5=token_usage, v6=standup config/history/updates, v7=retro history, v8=performance 1:1s/reviews/notes, v9=reporting history, v10=roadmap config/history, v11=multi-row roadmaps list seeded from the v10 singleton, v12=token_usage local-perf columns)- On startup: if stored version > current →
schema_mismatch = True(warn user); if stored version < current → run migrations - Session IDs: internal
new-<8hex>-<YYYY-MM-DD>, display<project-slug>-<YYYY-MM-DD>
Testing Conventions
- One test file per source module:
repl.py→test_repl.py,state.py→test_state.py - Group related tests in classes:
TestGracefulExit,TestStreaming,TestPriority - Use
pytestfixtures for shared setup (e.g._make_console()for rich Console with StringIO buffer) - Use
monkeypatchto avoid filesystem writes, network calls, and delays in tests - Test both happy path and edge cases (empty input, boundary values, immutability)
- Node tests live in
tests/unit/nodes/— split into ~9 files by node (analyzer, route, tasks, etc.) tests/integration/test_tui_smoke.pyboots the real TUI (yeaboi --dry-run) in a pseudo-terminal and quits it — the only test exercising the live raw-mode/alt-screen path. It guards dependency bumps (e.g.rich) that unit tests with StringIO consoles can't catch- Shared node test helpers in
tests/_node_helpers.py:make_completed_questionnaire(),make_dummy_analysis(),make_sample_features(),make_sample_stories(),make_sample_sprints() - Never modify
tests/integration/test_repl.py— it monkeypatches 10+ names inyeaboi.repland is the only test file with this level of coupling. Future tests should avoid this pattern. - Pytest markers:
slow(graph compilation),eval(golden evaluators),vcr(contract tests),smoke(live API)
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

