culture-guide

Workshop and scaffolding CLI for practical AI efficiency: learn core AI concepts, build your first agents, create useful CLIs, and adopt agent-first development patterns

What you get

• An agent-first CLI cited from teken (afi-cli) — the runtime package has no third-party dependencies.
• A mesh identity — culture.yaml (suffix + backend) and the matching prompt file for that backend (this repo ships backend: colleague → AGENTS.colleague.md; claude → CLAUDE.md, acp → AGENTS.md, gemini → GEMINI.md).
• The canonical guildmaster skill kit (11 skills) under .claude/skills/, vendored cite-don't-import. See docs/skill-sources.md.
• A build + deploy baseline — pytest, lint, the agent-first rubric gate, and PyPI Trusted Publishing wired into GitHub Actions.
• The named paradigm — docs/culture.md names the culture every cloned agent inherits (agent-first CLI, cite-don't-import, learn→teach, the all-backends rule, converge-don't-vibe, …) and cites where each tenet is enforced. Addressable from the CLI: culture-guide explain culture.

Quickstart

uv sync
uv run pytest -n auto                 # run the test suite
uv run culture-guide whoami            # identity from culture.yaml
uv run culture-guide learn             # self-teaching prompt (add --json)
uv run teken cli doctor . --strict    # the agent-first rubric gate CI runs

CLI

Every command supports --json. Results go to stdout, errors/diagnostics to stderr (never mixed). Exit codes: 0 success, 1 user error, 2 environment error, 3+ reserved.

Make it your own

1. Rename the package culture_guide/ and the culture-guide CLI/dist name throughout pyproject.toml, the package, tests/, sonar-project.properties, and this README.md. The name is hard-coded in ~100 places, so list every occurrence first — see the git grep discovery command in CLAUDE.md, the authoritative rename procedure.
2. Edit culture.yaml with your suffix and backend.
3. Rewrite CLAUDE.md for your agent and run /init.
4. Re-vendor only the skills you need from guildmaster (see docs/skill-sources.md).

See CLAUDE.md for the full conventions (version-bump-every-PR, the cicd PR lane, deploy setup).

Constant Colleague (Telegram responder)

A supervised, reset-surviving Telegram responder managed from the culture-guide CLI; it listens to a group and answers via an OpenAI/vLLM agent loop (strands-agents), colleague-swappable later.

Configure

Set these environment variables (via .env or your shell):

• TELEGRAM_AGENT_BOT_TOKEN — your Telegram bot token
• CONSTANT_COLLEAGUE_CHAT_ID — the Telegram group/chat ID to listen on
• COLLEAGUE_BASE_URL — OpenAI-compatible endpoint (default http://localhost:8001/v1)
• COLLEAGUE_MODEL — model name to use
• CONSTANT_COLLEAGUE_BOT_USERNAME — the bot's display username
• CONSTANT_COLLEAGUE_POLL_INTERVAL — seconds between getUpdates polls

Run

culture-guide listen start      # install + enable systemd --user unit (survives reboot)
culture-guide listen status     # is it live?
culture-guide listen stop
culture-guide listen restart
culture-guide listen logs       # prints the journalctl --user command

How it works

Pipeline: telegram-agent (receive getUpdates + send) → relevance gate (tag-override bypass; else reranker B → chat A cascade on the lobes vLLM endpoint; A-only fallback) → strands-agents agent loop (the mind) → reply; per-chat memory via eidetic; supervised by a systemd --user unit with lingering so it resumes after a server reset.

This added two runtime deps (telegram-agent[telegram], strands-agents[openai]) — culture-guide is no longer zero-third-party-dep.

License

Apache 2.0 — see LICENSE.