{"id":51626746,"url":"https://github.com/waitdeadai/effort-agent","last_synced_at":"2026-07-13T02:02:27.435Z","repository":{"id":351253068,"uuid":"1210051472","full_name":"waitdeadai/effort-agent","owner":"waitdeadai","description":"Process integrity enforcer — did you do the work thoroughly? effort.md + effort.memory for AI coding agents.","archived":false,"fork":false,"pushed_at":"2026-04-14T07:32:21.000Z","size":6568,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-14T09:28:56.042Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/waitdeadai.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-14T03:24:20.000Z","updated_at":"2026-04-14T07:32:25.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/waitdeadai/effort-agent","commit_stats":null,"previous_names":["waitdeadai/effort-agent"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/waitdeadai/effort-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/waitdeadai%2Feffort-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/waitdeadai%2Feffort-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/waitdeadai%2Feffort-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/waitdeadai%2Feffort-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/waitdeadai","download_url":"https://codeload.github.com/waitdeadai/effort-agent/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/waitdeadai%2Feffort-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35407393,"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-07-13T02:00:06.543Z","response_time":119,"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":[],"created_at":"2026-07-13T02:02:24.747Z","updated_at":"2026-07-13T02:02:27.421Z","avatar_url":"https://github.com/waitdeadai.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# effort-agent\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"effortagentmascot.png\" alt=\"effort-agent mascot\" width=\"200\" /\u003e\n\u003c/p\u003e\n\n**\"Your AI coding agent says 'Done.' after one pass. Then you find the bugs.\"**\n\n`effort-agent` ensures your AI coding agent actually does the work — thoroughly — on every iteration. Not just \"good enough.\" Not just \"should work.\" The actual work: verification, iteration, research, evidence. Write `effort.md` once (your process standards), then let `effort-agent` enforce it with `DONE | REDO | FAIL` verdicts.\n\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)\n\n---\n\n## The Problem\n\nAgentic AI systems (agents, coding engines, autonomous pipelines) are great at producing output quickly. But speed often comes at the cost of **process integrity**:\n\n- Agents claim \"Done.\" after a single pass\n- Verification steps (\"tests\") are skipped or assumed\n- \"Good enough\" language creeps into output\n- Research is skipped in favor of \"just implement\"\n- Placeholder code ships as finished work\n\n**taste-agent** answers \"Does it look right?\" (aesthetic/quality).\n**effort-agent** answers \"Did you do the work?\" (process integrity).\n\n## Quick Start\n\n```python\nfrom effort_agent import EffortAgent, EffortConfig, EffortVerdict\n\n# Create and enable agent\nagent = EffortAgent(\n    config=EffortConfig(\n        enabled=True,\n        level=\"thorough\",\n        always_verify=True,\n        no_shortcuts=True,\n    )\n)\n\n# Your agent's result (must have verification_commands)\nclass MyResult:\n    verification_commands = [\"pytest tests/ -v\"]\n    text = \"Implemented auth module with JWT. Done.\"\n\n# Evaluate\nresult = agent.evaluate(\n    task=\"Build JWT authentication module\",\n    agent_result=MyResult(),\n    file_contents={\"auth.py\": \"...\"},\n)\n\nif result.verdict == EffortVerdict.REDO:\n    print(f\"REDO: {result.reasoning}\")\n    # Feed back to agent for revision\nelif result.verdict == EffortVerdict.DONE:\n    print(\"Work meets effort standards.\")\n```\n\n## Key Features\n\n### Shortcut Detection\n\nDetects common shortcut language across 6 categories:\n\n| Category | Examples |\n|----------|----------|\n| `skipped_verification` | \"no need to run tests\", \"skip verification\" |\n| `good_enough_language` | \"good enough\", \"should work\", \"looks good\" |\n| `single_pass` | \"Done.\", \"Complete.\", \"All set.\" |\n| `vague_copy` | \"seamless\", \"cutting-edge\", \"we help you\" |\n| `assumptions` | \"assume it will work\", \"assuming correctness\" |\n| `placeholder_code` | \"// TODO\", \"placeholder\", \"stub\" |\n\n### Verification Enforcement\n\nWhen `always_verify=True`, the agent **must** provide `verification_commands` in its result. Empty or placeholder commands trigger a REDO.\n\n```python\n# This triggers REDO\nclass BadResult:\n    verification_commands = []  # Empty — no evidence of verification\n\n# This passes\nclass GoodResult:\n    verification_commands = [\"pytest tests/ -v --tb=short\"]\n```\n\n### Iteration Tracking\n\neffort-agent tracks draft counts per task and enforces minimums:\n\n- `efficient`: 1 draft (prototypes)\n- `thorough`: 2 drafts (default, standard development)\n- `exhaustive`: 3 drafts (production systems)\n- `perfectionist`: 4 drafts (user-facing, polished work)\n\n### Research Enforcement\n\nWhen `research_before_code=True`, the agent must show evidence of research before implementation — search queries, doc lookups, existing code inspection.\n\n### Effort Memory (JSONL)\n\nAll evaluations are recorded to `effort.memory` (JSONL append-only log):\n\n```jsonl\n{\"entry_id\": \"em-a1b2c3d4\", \"timestamp\": \"2026-04-13T10:30:00Z\",\n \"task_description\": \"Build user auth module\", \"file_path\": \"auth.py\",\n \"verdict\": \"REDO\", \"reasoning\": \"Single-pass completion detected\",\n \"issues\": [\"single_pass\"], \"category\": \"process\", \"was_applied\": false}\n```\n\nQuery the memory:\n```python\nagent.memory.redo_rate()       # 0.15 = 15% REDO rate\nagent.memory_summary()          # Full statistics\nagent.memory.is_duplicate(task) # Check for repeated tasks\n```\n\n## Installation\n\n```bash\npip install effort-agent\n```\n\nWith extras:\n```bash\npip install effort-agent[dev]        # Development dependencies\npip install effort-agent[sqlite]    # SQLite iteration store\n```\n\n## Configuration\n\n```python\nfrom effort_agent import EffortConfig\n\nconfig = EffortConfig(\n    enabled=True,                    # Master kill-switch\n    level=\"thorough\",                # Preset level\n    min_drafts=2,                    # Minimum draft cycles\n    always_verify=True,              # Require verification evidence\n    no_shortcuts=True,               # Block shortcut language\n    shortcuts_blocked=[],            # Custom shortcut patterns\n    research_before_code=True,       # Enforce pre-code research\n    require_effort_md=False,         # Fail if effort.md missing\n    fail_on_single_pass=True,        # Block single-pass language\n    fail_on_good_enough=True,        # Block \"good enough\" language\n)\n```\n\n## effort.md Format\n\nCreate `effort.md` in your project root for declarative process definition:\n\n```markdown\n# Effort — My Project\n\n## 1. Process Philosophy\nNo shortcuts allowed. Every implementation requires research,\ndrafting, verification, and iteration.\n\n## 2. Verification Requirements\n- All code changes MUST be verified with tests\n- No \"should work\" or \"looks good\" language\n\n## 3. Iteration Standards\n- Minimum drafts per task: 2\n- Research MUST precede implementation\n\n## 4. Forbidden Shortcuts\n- \"Good enough\" language\n- Single-pass completion\n```\n\nLoad it:\n```python\nagent = EffortAgent(\n    config=EffortConfig(enabled=True),\n    effort_md_path=\"effort.md\",\n)\n```\n\n## Integrations\n\n### ForgeGod\n\n```python\nfrom effort_agent.integration import ForgeGodEffortIntegrator\n\nintegrator = ForgeGodEffortIntegrator(\n    forgegod=my_forgegod_instance,\n    effort_md_path=\"/opt/forgegod/effort.md\",\n)\n\n# In ForgeGod's loop\npost = integrator.post_implementation_check(\n    task=task.description,\n    agent_result=result,\n    file_contents=result.changed_files,\n)\n\nif post.verdict == EffortVerdict.REDO:\n    forgegod.reflection_loop.add_feedback(issues=post.issues)\n```\n\nSee [docs/INTEGRATION.md](docs/INTEGRATION.md) for more patterns (CI/CD, FastAPI, taste-agent).\n\n## Directory Structure\n\n```\neffort-agent/\n├── LICENSE\n├── README.md\n├── effortagentmascot.png\n├── pyproject.toml\n├── src/effort_agent/\n│   ├── __init__.py\n│   ├── core/\n│   │   ├── effort_agent.py        # Main EffortAgent class\n│   │   ├── verdict.py              # VERDICT enum\n│   │   ├── effort_config.py        # EffortConfig pydantic model\n│   │   ├── effort_memory.py        # JSONL memory store + MemoryEntry\n│   │   └── effort_result.py        # EffortResult dataclass\n│   ├── evaluators/\n│   │   ├── shortcut_detector.py    # Regex pattern detector\n│   │   ├── verification_enforcer.py\n│   │   ├── iteration_tracker.py\n│   │   └── research_enforcer.py\n│   ├── models/\n│   │   └── effort_spec.py          # Parsed effort.md\n│   ├── cli/\n│   │   ├── main.py                 # Click CLI entry point\n│   │   ├── gate_cmd.py             # effort gate (CI/CD)\n│   │   ├── init_cmd.py             # effort init\n│   │   ├── lint_cmd.py             # effort lint\n│   │   └── evaluate_cmd.py         # effort evaluate\n│   └── integration/\n│       └── mcp_server.py           # MCP stdio JSON-RPC server\n├── tests/\n└── docs/\n    ├── GETTING_STARTED.md\n    └── EFFORT_SPEC_FORMAT.md\n```\n\n## Verdict Reference\n\n| Verdict | Meaning | Agent Action |\n|---------|---------|--------------|\n| `DONE` | Work meets effort standards | Proceed |\n| `REDO` | Shortcuts detected | Return to agent with issues |\n| `FAIL` | Catastrophic failure | Halt execution |\n\n## Dependencies\n\n- `pydantic\u003e=2.11` — Data validation and settings\n- `httpx\u003e=0.28` — HTTP client (for future API integrations)\n- `json-repair\u003e=0.44` — JSON repair (for corrupted memory files)\n\n## License\n\nApache 2.0 — see [LICENSE](LICENSE).\n\n---\n\n**effort-agent** is part of the WAITDEAD system (Audit. Plan. Scale.) and complements [taste-agent](https://github.com/waitdead/taste-agent).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwaitdeadai%2Feffort-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwaitdeadai%2Feffort-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwaitdeadai%2Feffort-agent/lists"}