{"id":50659181,"url":"https://github.com/beogip/code-first-agents","last_synced_at":"2026-06-08T01:07:49.604Z","repository":{"id":350498635,"uuid":"1207026260","full_name":"beogip/code-first-agents","owner":"beogip","description":"Design patterns for building reliable AI agents by moving deterministic work from the LLM to code","archived":false,"fork":false,"pushed_at":"2026-05-22T00:09:30.000Z","size":430,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-22T08:51:15.767Z","etag":null,"topics":["agent-architecture","ai-agents","ai-engineering","code-first","design-patterns","deterministic","llm","skill-orchestration"],"latest_commit_sha":null,"homepage":"https://code-first-agents.com/","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/beogip.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-10T13:52:26.000Z","updated_at":"2026-05-21T18:08:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/beogip/code-first-agents","commit_stats":null,"previous_names":["beogip/code-first-agents"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/beogip/code-first-agents","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beogip%2Fcode-first-agents","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beogip%2Fcode-first-agents/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beogip%2Fcode-first-agents/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beogip%2Fcode-first-agents/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/beogip","download_url":"https://codeload.github.com/beogip/code-first-agents/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beogip%2Fcode-first-agents/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34043836,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-07T02:00:07.652Z","response_time":124,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-architecture","ai-agents","ai-engineering","code-first","design-patterns","deterministic","llm","skill-orchestration"],"created_at":"2026-06-08T01:07:48.914Z","updated_at":"2026-06-08T01:07:49.584Z","avatar_url":"https://github.com/beogip.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Code-First Agents\n\n**Design patterns for building reliable AI agents by moving deterministic work from the LLM to code.**\n\nYour agent works. Until it doesn't. And you can't tell why.\n\nThe LLM picks the wrong branch. It skips a step. It hallucinates a field name. You can't write a test for any of it because the decision happened inside a black box.\n\nCode-First Agents is a set of patterns for moving decision-making out of the LLM and into deterministic code. The LLM orchestrates. Code executes. The more you push into code, the less you depend on probabilistic output for things that should be deterministic.\n\n## Patterns\n\n| Pattern | Description |\n|---------|-------------|\n| [Deterministic Tools](https://beogip.github.io/code-first-agents/patterns/deterministic-tools.html) | How to build CLI tools that do deterministic work and output JSON. The tool contract, the output spectrum, and progressive examples. |\n| [Skill Orchestration](https://beogip.github.io/code-first-agents/patterns/skill-orchestration.html) | How to write SKILL.md files that consume tool output. The LLM as executor, chaining tools, guards, and the verbatim execution principle. |\n\nFor the formal specification of both patterns, including the contract, trade-offs, reference implementations, and evolution history, see [`specs/code-first-agents.md`](specs/code-first-agents.md).\n\n## The spectrum\n\nTools exist on a spectrum based on how much decision-making they absorb from the LLM:\n\n| Level | Tool returns | LLM does | Example |\n|-------|-------------|----------|---------|\n| **1. Data** | Structured facts | Interprets, decides | [`get-issue-signals.ts`](examples/tools/get-issue-signals.ts) |\n| **2. Classification** | Data + classification | Reads the class, branches | [`classify-issue.ts`](examples/tools/classify-issue.ts) |\n| **3. Instructions** | Literal procedure | Executes verbatim | [`analyze-issue.ts`](examples/tools/analyze-issue.ts) |\n\nAt Level 3, the tool becomes a prompt factory. The LLM is a pure executor.\n\n## Examples\n\nThe [`examples/`](examples/) directory contains a complete GitHub issue planning workflow that demonstrates the three levels. All tools run with [Bun](https://bun.sh):\n\n```bash\n# Level 1: raw signals from the issue body\nbun examples/tools/get-issue-signals.ts --owner acme --repo app --issue 42\n\n# Level 2: deterministic classification\nbun examples/tools/classify-issue.ts --owner acme --repo app --issue 42\n\n# Level 3: complete planning procedure\nbun examples/tools/analyze-issue.ts --owner acme --repo app --issue 42\n```\n\nSee [`examples/skills/plan-issue/SKILL.md`](examples/skills/plan-issue/SKILL.md) for a full skill that orchestrates `analyze-issue.ts` at Level 3.\n\n## Specs\n\n- [Code-First Agents Spec](specs/code-first-agents.md): formal specification covering the tool contract, skill orchestration, trade-offs, reference implementations, and evolution history.\n- [Anti-Patterns Registry](specs/anti-patterns/): catalog of heuristics for detecting when a skill or tool violates the code-first contract.\n\n## Site\n\nThe full documentation lives at **https://beogip.github.io/code-first-agents/**.\n\nThe site source (HTML, CSS, markdown mirrors) lives in the [`gh-pages` branch](https://github.com/beogip/code-first-agents/tree/gh-pages). This branch (`main`) holds the example tools, the example skill, and the repo metadata.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on proposing new patterns and adding examples.\n\n## License\n\n[MIT](LICENSE)\n\n## Author\n\nBuilt by [Juan Gipponi](https://www.linkedin.com/in/juan-gipponi).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeogip%2Fcode-first-agents","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbeogip%2Fcode-first-agents","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeogip%2Fcode-first-agents/lists"}