{"id":49313627,"url":"https://github.com/danielmeppiel/genesis","last_synced_at":"2026-04-26T14:03:18.830Z","repository":{"id":353818828,"uuid":"1221017084","full_name":"danielmeppiel/genesis","owner":"danielmeppiel","description":"First-principles substrate for designing agentic primitives. From PROSE.","archived":false,"fork":false,"pushed_at":"2026-04-25T19:08:59.000Z","size":64,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-25T19:14:05.374Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/danielmeppiel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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-25T16:37:06.000Z","updated_at":"2026-04-25T19:09:05.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/danielmeppiel/genesis","commit_stats":null,"previous_names":["danielmeppiel/genesis"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/danielmeppiel/genesis","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielmeppiel%2Fgenesis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielmeppiel%2Fgenesis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielmeppiel%2Fgenesis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielmeppiel%2Fgenesis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/danielmeppiel","download_url":"https://codeload.github.com/danielmeppiel/genesis/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielmeppiel%2Fgenesis/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32299644,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T09:34:17.070Z","status":"ssl_error","status_checked_at":"2026-04-26T09:34:00.993Z","response_time":129,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":[],"created_at":"2026-04-26T14:03:17.329Z","updated_at":"2026-04-26T14:03:18.824Z","avatar_url":"https://github.com/danielmeppiel.png","language":null,"funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"branding/logo.svg\" alt=\"genesis\" width=\"180\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003egenesis\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eMarkdown that steers an LLM is code. Design it before you write it.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/danielmeppiel/genesis?style=flat\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/danielmeppiel/genesis/commits/main\"\u003e\u003cimg src=\"https://img.shields.io/github/last-commit/danielmeppiel/genesis?style=flat\" alt=\"Last Commit\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n**Genesis ports the software architect's role to agentic systems -- decomposition, contracts, and cross-cutting concerns applied to workflows where LLMs are the runtime.**\n\nSoftware engineering needed architecture, not just style guides, the moment systems crossed a complexity threshold. AI-coding-agent systems crossed that threshold a while ago. The downstream cost is paid by the developers using the agents you ship: poor user experience, unreliable behavior, regressions that look like the model failing when in fact the system around the model has no architecture. Genesis is the architectural layer that was missing.\n\n## Install\n\n```bash\nnpx skills add danielmeppiel/genesis\n```\n\nZero global install. Works with Claude Code, Cursor, Codex, OpenCode, GitHub Copilot, and 41+ more agents -- see [skills.sh](https://skills.sh).\n\nAlready using [apm](https://github.com/microsoft/apm) (manifest + lockfile)?\n\n```bash\napm install danielmeppiel/genesis\n```\n\n---\n\n## You've felt this\n\nIf you've built anything non-trivial with AI coding agents, one of these has happened to you:\n\n- **Monolithic instruction files.** The forty-line rule file became four hundred. No modules, no boundaries, no separation of concerns. Every change requires reading the whole thing, and the agent silently ignores the half it cannot fit in attention.\n- **Copy-paste duplication across primitives.** The same convention lives in three skills and two rule files. One was edited last week; the agent now contradicts itself depending on which path the harness loads first.\n- **Behavioral drift on long sessions.** Constraints that held at turn one are silently dropped by turn twenty. There is no contract, no acceptance check, no test at the boundary -- the regression ships and you find out from the user.\n\nGenesis names the primitives, the patterns, and the refactor moves -- so you compose instead of copy, and review instead of guess.\n\n---\n\n## Quick Start\n\nAfter install, summon the skill in your agent (Claude Code, Cursor, GitHub Copilot, OpenCode, Codex) by typing `/genesis` followed by what you want designed:\n\n```\n/genesis I want every PR on my repo reviewed for missing tests, undocumented\npublic API, and unsafe migrations -- aggregated into one comment. Never\napprove, never auto-merge.\n```\n\nYou will get a named pattern, an execution diagram, an acceptance test, and a written plan -- before any file is touched.\n\nFor how `/genesis` resolves on each harness, see [Runtimes](#runtimes).\n\n---\n\n## What it produces\n\nCold-load the skill on the Quick Start prompt. Before writing a single file, genesis proposes this layout:\n\n```\n.github/skills/pr-review/\n├── SKILL.md                       # entrypoint, 8-step contract\n├── agents/\n│   ├── pr-tests-lens.agent.md     # missing-tests reviewer (fresh context)\n│   ├── pr-docs-lens.agent.md      # public-API doc reviewer\n│   ├── pr-migration-lens.agent.md # unsafe-migration reviewer\n│   └── pr-synthesizer.agent.md    # arbiter, dissent-weighted\n├── rules/\n│   └── review-output.md           # auto-attached output schema\n├── assets/\n│   ├── severity-rubric.md         # acceptance gate\n│   └── findings.template.md       # plan persistence shape\n└── triggers/\n    └── on-pull-request.yml        # event binding\n```\n\nThen it justifies each piece against the genesis catalogue:\n\n| Component | Pattern | Why this, not that |\n|---|---|---|\n| Three lens agents in fresh contexts | [A1 Panel](skills/genesis/assets/architectural-patterns.md#a1-panel-multi-lens-deliberation) + [B1 Fan-Out + Synthesizer](skills/genesis/assets/design-patterns.md#b1-fan-out--synthesizer) | Independent lenses must not share a context; later lenses inherit attention drift from earlier ones. |\n| Dissent-weighted synthesizer | [A1 Panel arbiter](skills/genesis/assets/architectural-patterns.md#a1-panel-multi-lens-deliberation) | A single vote is not consensus when reviewers disagree on the same hunk. |\n| Output schema as auto-attached rule | [Scope-Attached Rule File](skills/genesis/assets/primitives.md#3-scope-attached-rule-file) + [S4 Validation Decorator](skills/genesis/assets/design-patterns.md#s4-validation-decorator) | Every lens emits the same shape; downstream parsing and assertions stay mechanical. |\n| Trigger as a separate file | [A6 Event-Driven](skills/genesis/assets/architectural-patterns.md#a6-event-driven) | Decouples *when* from *what*; the same skill works in any harness. |\n| `findings.template.md` | [B4 Plan Memento](skills/genesis/assets/design-patterns.md#b4-plan-memento) | State outside the context window; a re-run on the same PR is comparable. |\n\nObject diagram of the runtime shape:\n\n```mermaid\nclassDiagram\n    class PrReviewSkill {\n        +SKILL.md\n        +invoke(pr_diff)\n    }\n    class TestsLens {\n        +context: fresh\n    }\n    class DocsLens {\n        +context: fresh\n    }\n    class MigrationLens {\n        +context: fresh\n    }\n    class Synthesizer {\n        +arbitrate(findings) verdict\n    }\n    class OutputSchemaRule {\n        \u003c\u003cauto-attached rule\u003e\u003e\n    }\n    class FindingsMemento {\n        \u003c\u003cplan persistence\u003e\u003e\n    }\n    PrReviewSkill o-- TestsLens : spawns\n    PrReviewSkill o-- DocsLens : spawns\n    PrReviewSkill o-- MigrationLens : spawns\n    PrReviewSkill o-- Synthesizer : spawns\n    TestsLens ..\u003e OutputSchemaRule : enforces\n    DocsLens ..\u003e OutputSchemaRule : enforces\n    MigrationLens ..\u003e OutputSchemaRule : enforces\n    Synthesizer ..\u003e OutputSchemaRule : enforces\n    Synthesizer ..\u003e FindingsMemento : writes\n```\n\nThe file you eventually author is the easy part. The composition above is what was missing.\n\n---\n\n## Same skill, three prompts, three architectures (and why)\n\nThree cold-load runs of the genesis skill -- same skill, fresh context each time, three different operator prompts -- yielded three materially different (and each justified) output architectures:\n\n| Operator prompt (excerpt) | Output shape | Patterns selected (and rejected) | Worked example |\n|---|---|---|---|\n| \"Draft release notes from CHANGELOG entries\" | 6 files: 1 skill + 2 assets + 3 scripts; single thread | [A9 Supervised Execution](skills/genesis/assets/architectural-patterns.md#a9-supervised-execution-plan-deterministic-execute-verify) + [S7 Deterministic Tool Bridge](skills/genesis/assets/design-patterns.md#s7-deterministic-tool-bridge) + [S4 Validation Decorator](skills/genesis/assets/design-patterns.md#s4-validation-decorator). [A1 Panel](skills/genesis/assets/architectural-patterns.md#a1-panel-multi-lens-deliberation) **rejected** (lens-count gate did not fire). | [examples/03](skills/genesis/examples/03-release-notes-single-skill.md) |\n| \"Review every PR: gather findings and present them\" | 17 primitives: 6 personas + 4 assets + 3 scripts + trigger + entrypoint + rule + evals | [A6 Event-Driven](skills/genesis/assets/architectural-patterns.md#a6-event-driven) + [A1 Panel](skills/genesis/assets/architectural-patterns.md#a1-panel-multi-lens-deliberation) + Dissent-Weighted arbiter. [R1 Split](skills/genesis/assets/refactor-patterns.md#r1-split-decomposition) considered, applied at lens content as [R3 Extract](skills/genesis/assets/refactor-patterns.md#r3-extract-promote-to-module). | [examples/04](skills/genesis/examples/04-pr-review-advisory.md) |\n| \"Review every PR: emit APPROVE or REJECT verdict\" | 9 primitives + S7 deterministic bridges + S4 schema gate + post-emit verifier loop + graceful tool probes | Regime change: [A9](skills/genesis/assets/architectural-patterns.md#a9-supervised-execution-plan-deterministic-execute-verify) + [S7](skills/genesis/assets/design-patterns.md#s7-deterministic-tool-bridge) + [S4](skills/genesis/assets/design-patterns.md#s4-validation-decorator) hardened. [A8 Alignment Loop](skills/genesis/assets/architectural-patterns.md#a8-alignment-loop-bounded-iteration-with-goal-steward), [B5 Acceptance Observer](skills/genesis/assets/design-patterns.md#b5-acceptance-observer), [R1 Split](skills/genesis/assets/refactor-patterns.md#r1-split-decomposition) all **considered and rejected with WHEN-clause grounding**. | [examples/05](skills/genesis/examples/05-pr-review-verdict.md) |\n\nNotice row 3: removing the operator's \"gather and present, never decide\" constraint flipped the system from advisory to consequential. Genesis hardened the existing pipeline with deterministic bridges and a verifier loop -- it did **not** reach for new orchestration patterns. That restraint, with its rejection logic shown, is the discipline being demonstrated. Each example is the verbatim output of a fresh agent session that loaded only `skills/genesis/SKILL.md` and the operator prompt.\n\n---\n\n## The architect's role, ported\n\nThe six decisions a software architect makes map to AI-coding-agent systems row for row. The code is Markdown; the runtime is an LLM; the structural failure modes are the same.\n\n| Classical concern | Agent-architect equivalent | Genesis deliverable |\n|---|---|---|\n| Greenfield design | Partition a goal into agents, skills, and instruction scopes; define execution boundaries | Skill dependency graph + handoff packet + `plan.md` |\n| Service decomposition | Identify where one agent ends and another begins; prevent skill coupling | Primitive dependency graph + [R1 Split](skills/genesis/assets/refactor-patterns.md#r1-split-decomposition) when seams drift |\n| Integration and contracts | Design skill inputs, outputs, and agent-to-agent handoffs | Interface sketch (trigger, inputs, outputs) + sequence diagram |\n| Cross-cutting concerns | Auth context, safety rails, encoding rules that apply across all agents | Shared [Scope-Attached Rule Files](skills/genesis/assets/primitives.md#3-scope-attached-rule-file) + [S6 Rule Bridge](skills/genesis/assets/design-patterns.md#s6-rule-bridge) pattern |\n| Refactoring strategy | Identify drifted skills and conflicting instruction files; pay prompt debt | Skill refactor plan using [R1-R4 patterns](skills/genesis/assets/refactor-patterns.md) |\n| Architecture review | Evaluate proposed designs for consistency; prevent prompt sprawl | [A1 Panel pattern](skills/genesis/assets/architectural-patterns.md#a1-panel-multi-lens-deliberation) (multi-lens review) + severity-rubric compliance check |\n\n---\n\n## Primitives\n\nEvery harness implements the same six concepts under different folder names. Genesis names them once so the vocabulary outlives any one tool.\n\n| Concept | What it is | Common terms |\n|---|---|---|\n| [Persona Scoping File](skills/genesis/assets/primitives.md#1-persona-scoping-file) | A document loaded at session start to scope who the agent is. | \"agent file\", \"subagent\", \"mode\" |\n| [Module Entrypoint](skills/genesis/assets/primitives.md#2-module-entrypoint) | A bundled, self-contained capability with assets and a contract. | \"skill\", \"module\" |\n| [Scope-Attached Rule File](skills/genesis/assets/primitives.md#3-scope-attached-rule-file) | A constraint that auto-applies to a path or context. | \"instruction\", \"rule\", \"memory\" |\n| [Child-Thread Spawn](skills/genesis/assets/primitives.md#4-child-thread-spawn) | A primitive that creates a new context window running in parallel. | \"subagent thread\", \"Task tool\" |\n| [Trigger Orchestrator](skills/genesis/assets/primitives.md#5-trigger-orchestrator) | A declarative pipeline that runs primitives on events. | \"workflow\", \"hook\", \"automation\" |\n| [Plan Persistence](skills/genesis/assets/primitives.md#6-plan-persistence) | A stable artifact (file or DB) holding the active plan across turns. | \"plan.md\", \"TODO state\", \"checkpoints\" |\n\nThese names are deliberately generic. The architecture must outlive any one tool.\n\n---\n\n## Patterns\n\nGenesis maps the Gang-of-Four onto agent design. The classical name is your Rosetta Stone; the AI-native name encodes the LLM-physics specifics (context isolation, attention decay).\n\n| GoF axis | Classical | AI-native | When |\n|---|---|---|---|\n| Creational | Factory Method | [Thread Spawn](skills/genesis/assets/design-patterns.md#c3-thread-spawn) | Work benefits from a fresh context window |\n| Structural | Facade | [Orchestrator Facade](skills/genesis/assets/design-patterns.md#s3-orchestrator-facade) | A multi-step capability needs to look like one signature |\n| Behavioral | Master-Worker | [Fan-Out + Synthesizer](skills/genesis/assets/design-patterns.md#b1-fan-out--synthesizer) | \u003e=3 independent lenses, no shared state |\n| Behavioral | *(no analog)* | **[Attention Anchor](skills/genesis/assets/design-patterns.md#b8-attention-anchor)** | Re-inject goal + constraints at every re-grounding boundary |\n\n**[Attention Anchor](skills/genesis/assets/design-patterns.md#b8-attention-anchor) has no classical counterpart -- it exists because LLM attention degrades over distance.** Without periodic re-injection of goal and hard constraints, long sessions silently drift from the original intent. It is the highest-leverage behavioral pattern for any non-trivial agent task.\n\nFull catalogue (23 design patterns + 9 architectural patterns + 4 refactor patterns): [`skills/genesis/assets/design-patterns.md`](skills/genesis/assets/design-patterns.md), [`skills/genesis/assets/architectural-patterns.md`](skills/genesis/assets/architectural-patterns.md), [`skills/genesis/assets/refactor-patterns.md`](skills/genesis/assets/refactor-patterns.md).\n\n---\n\n## The architect's loop\n\n```\n1.  state goal          --\u003e one sentence, observable outcome\n2.  name primitives     --\u003e which substrate concepts will you use?\n3.  pick pattern        --\u003e architectural shape, then design patterns; justify in one line\n3.5 compose or build?   --\u003e can an existing module satisfy this?\n4.  draw uml            --\u003e mermaid, validate it renders\n5.  acceptance          --\u003e what proves it works?\n6.  persist plan        --\u003e write plan.md (or equivalent) before coding\n7.  implement           --\u003e author files; commit\n7b. reload plan         --\u003e on every meaningful turn, re-read the plan\n8.  stop condition      --\u003e ship, or stop the design\n```\n\nSteps 6 and 7b are non-negotiable. They realize **[B4 Plan Memento](skills/genesis/assets/design-patterns.md#b4-plan-memento)** (state outside the context window) and **[B8 Attention Anchor](skills/genesis/assets/design-patterns.md#b8-attention-anchor)** (re-inject goal + constraints on every meaningful turn). Together they defeat the silent drift that ends most long agent sessions.\n\n---\n\n## Runtimes\n\n| Harness | Persona file format | Skill folder | Adapter |\n|---|---|---|---|\n| Claude Code        | `.claude/agents/*.md`        | `.claude/skills/`   | [adapter](skills/genesis/assets/runtime-affordances/per-harness/claude-code.md) |\n| GitHub Copilot CLI | `.github/agents/*.agent.md`  | `.github/skills/`   | [adapter](skills/genesis/assets/runtime-affordances/per-harness/copilot.md)     |\n| Cursor             | `.cursor/rules/*.mdc`        | `.cursor/skills/`   | [adapter](skills/genesis/assets/runtime-affordances/per-harness/cursor.md)      |\n| OpenCode           | `.opencode/agent/*.md`       | `.opencode/skills/` | [adapter](skills/genesis/assets/runtime-affordances/per-harness/opencode.md)    |\n| Codex              | `AGENTS.md` files            | `~/.codex/skills/`  | [adapter](skills/genesis/assets/runtime-affordances/per-harness/codex.md)       |\n\nThe primitives are the same. Only the file names change.\n\n---\n\n## Read more\n\n- [`skills/genesis/examples/`](skills/genesis/examples/) -- five worked designs with operator prompts, pattern reasoning, and considered-and-rejected alternatives.\n- [`skills/genesis/SKILL.md`](skills/genesis/SKILL.md) -- the skill itself; the eight-step process and progressive-disclosure protocol.\n- [`skills/genesis/agents/genesis-architect.agent.md`](skills/genesis/agents/genesis-architect.agent.md) -- the persona file.\n- [`skills/genesis/assets/`](skills/genesis/assets/) -- the loadable knowledge base (primitives, patterns, anti-patterns, refactor moves, runtime affordances).\n- [`dev/skills/genesis-evals/`](dev/skills/genesis-evals/) -- contributor-scope layout for maintainer-only primitives (eval scenarios) that must NOT ride into the published bundle. See `module-system-adapters/apm.md` \"APM publish-time rules\" for why.\n\n---\n\n**Apache 2.0 licensed.** Companion long-form book [The Agentic SDLC Handbook](https://danielmeppiel.github.io/agentic-sdlc-handbook/) is CC BY-NC 4.0; this skill is permissive on purpose so it can load into any agent harness. If two failure modes above matched something you ship, [open an issue](https://github.com/danielmeppiel/genesis/issues/new) with which one -- that is the data that shapes the next pattern.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanielmeppiel%2Fgenesis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdanielmeppiel%2Fgenesis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanielmeppiel%2Fgenesis/lists"}