{"id":51526655,"url":"https://github.com/prabhuakshay/forge","last_synced_at":"2026-07-08T22:01:17.509Z","repository":{"id":366511555,"uuid":"1276591903","full_name":"prabhuakshay/forge","owner":"prabhuakshay","description":"Opinionated Python project workflow as a Claude Code plugin: plan → build → check → audit → release, with hook-enforced gates, durable design directives, and docs/.env-in-sync guarantees.","archived":false,"fork":false,"pushed_at":"2026-06-22T06:58:41.000Z","size":178,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-22T07:26:18.232Z","etag":null,"topics":["agent","ai","anthropic","claude","claude-code","code-quality","developer-tools","mypy","plugin","pre-commit","pytest","python","ruff","uv","workflow"],"latest_commit_sha":null,"homepage":null,"language":"Python","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/prabhuakshay.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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-06-22T05:50:58.000Z","updated_at":"2026-06-22T06:57:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/prabhuakshay/forge","commit_stats":null,"previous_names":["prabhuakshay/forge"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/prabhuakshay/forge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prabhuakshay%2Fforge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prabhuakshay%2Fforge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prabhuakshay%2Fforge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prabhuakshay%2Fforge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/prabhuakshay","download_url":"https://codeload.github.com/prabhuakshay/forge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prabhuakshay%2Fforge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35279442,"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-08T02:00:06.796Z","response_time":61,"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","ai","anthropic","claude","claude-code","code-quality","developer-tools","mypy","plugin","pre-commit","pytest","python","ruff","uv","workflow"],"created_at":"2026-07-08T22:01:16.480Z","updated_at":"2026-07-08T22:01:17.494Z","avatar_url":"https://github.com/prabhuakshay.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# forge\n\n[![ci](https://github.com/prabhuakshay/forge/actions/workflows/ci.yml/badge.svg)](https://github.com/prabhuakshay/forge/actions/workflows/ci.yml)\n[![release](https://img.shields.io/github/v/release/prabhuakshay/forge?sort=semver)](https://github.com/prabhuakshay/forge/releases/latest)\n[![python](https://img.shields.io/badge/python-3.10%E2%80%933.13-blue)](https://github.com/prabhuakshay/forge/blob/main/pyproject.toml)\n\nAn opinionated **Python project workflow** as a Claude Code plugin. It makes the\nquality bar *executable* and makes the agent run it on every loop — so projects\ncome out consistent, stable, well-documented, and honest about their own state.\n\n## The loop\n\n```\n/forge:init  →  /forge:plan  →  /forge:build  →  /forge:check  →  /forge:review  →  /forge:audit  →  /forge:release\n                     ▲                                                                                       │\n                     └──────────────── /forge:decide (capture durable intent) ◄──────────────────────────────┘\n```\n\n| Command | Phase | Gate it satisfies |\n|---|---|---|\n| `/forge:init` | Scaffold a project (or retrofit one) with the full toolchain \u0026 docs | — |\n| `/forge:plan` | Turn a request into an atomic checklist before any code | plan exists |\n| `/forge:build` | Implement a plan item-by-item, tests from the spec | — |\n| `/forge:check` | Code gate: ruff + mypy + pytest/coverage | **unblocks commit** |\n| `/forge:audit` | Non-code sync: docs↔code, `.env`, lockfile, deps, metadata | **unblocks push/publish** |\n| `/forge:review` | Quality + correctness + directive/reference compliance | **unblocks commit** (projects with directives or governing references) |\n| `/forge:release` | Version bump, changelog, build, publish | — |\n| `/forge:decide` | Record a durable directive + ADR | binds all future work |\n| `/forge:reference` | Install/author scoped style references (django, cli, …) | catches style drift |\n| `/forge:docs` | Crawl codebase, find undocumented features, write/expand markdown in docs/ | — |\n| `/forge:status` | Snapshot of where the project stands: gates, dirty set, references, overrides | — |\n| `/forge:override` | Arm a one-shot, logged bypass of a gate (check, audit, review, stop, plan, uv) | the audited escape hatch |\n\n## What makes it stick\n\n**The gates are enforced by hooks, not goodwill:**\n\n- **PostToolUse** auto-formats every `.py` you touch in a forge-enabled project\n  (`ruff format` + safe fixes) and invalidates any stale \"green\" result.\n- **PreToolUse** blocks `git commit` unless `/forge:check` is green for the current\n  tree, blocks `git push`/publish unless `/forge:audit` is green, blocks `git\n  commit` unless `/forge:review` is green for projects that have binding directives\n  or a governing style reference, blocks source edits with no active plan, and\n  blocks non-uv dependency commands (pip, `uv pip install`, requirements files) —\n  deps go through `uv add`/`uv remove`.\n- **Stop** fires automatically when the agent tries to *end its turn* and won't\n  let it stop on a broken tree. It runs format and lint (whole-tree) and the\n  env-var drift check (vars read in code but undocumented in `.env.example`), plus\n  — only when files have been edited since the last green check — mypy scoped to\n  exactly those files (and skipped entirely when nothing is dirty, since types\n  are already proven; mypy still follows imports out of the changed files, so a\n  cross-file break is still caught). It deliberately skips the test suite, which\n  is the slower commit gate's job. A failure isn't a wall: the reasons are fed\n  back so the agent keeps working until the tree is green. If a broken state is a\n  *deliberate* stopping point, `/forge:override stop \"\u003cwhy\u003e\"` releases it (logged).\n- **SessionStart** injects the project's binding directives into every session.\n\nEvery block has a **logged one-shot override** so a real hotfix is never held\nhostage — but the bypass is recorded, never silent. Arm one with `/forge:override\n\u003cgate\u003e \"\u003cwhy\u003e\"` (or by writing the sentinel `.forge/override-\u003cgate\u003e` by hand); the\nnext matching gated action is allowed exactly once and the skip is appended to the\noverride trail in `.forge/state.json`. `/forge:status` shows what's armed before it\nfires and the full history after.\n\n**The gates are a workflow guardrail, not a security sandbox.** Two deliberate\nproperties follow from that. First, the hooks *fail open*: a hook that hits\nmalformed input or an unexpected error gets out of the way rather than wedging your\ntool call. Second, the command parser that recognises `git commit` / `git push` /\nnon-uv dependency commands is built to see through ordinary command shapes (paths,\nenv prefixes, wrappers, `sh -c '…'`), not determined obfuscation — exotic quoting or\nan `eval` can still slip past it. This is by design: forge keeps an honest workflow\nhonest and makes the quality bar the path of least resistance; it is not an\nadversarial boundary. What it *does* guarantee is that every bypass that happens\nthrough the front door is logged, never silent.\n\nThe type check (mypy) only runs when the project actually configures it — a\n`[tool.mypy]` table, a `mypy.ini`/`.mypy.ini`, or a `[mypy]` section in\n`setup.cfg`. A project\nthat doesn't type-check isn't forced red on a tool it doesn't use; forge-scaffolded\nprojects ship the config, so they stay covered.\n\n**Durable intent is captured, not lost.** When you tell the agent how something\nmust be designed, `/forge:decide` writes it as a binding directive\n(`.forge/directives.md`) plus a dated ADR (`docs/decisions/`). The directives are\nre-injected every session and enforced in review — so no future agent can quietly\nignore a decision you already made.\n\n**Docs can't silently drift.** `/forge:audit` runs the `doc-sync-auditor` agent,\nwhich is grounded by design: it only reports doc↔code drift it can tie to a\n`file:line`, so it catches real staleness without hallucinating.\n\n**Style stays consistent via scoped references.** Install convention guides\n(`/forge:reference add django`) that govern a subset of files by glob — `django.md`\ncovers your Django code, `cli.md` your CLI code, `python-base.md` all Python\nsource (`src/**/*.py` by default — tune the glob for your layout). They\nwork two ways: the relevant reference is **injected into context the moment you\nedit a file it governs** (once per session), and the grounded `reference-auditor`\nchecks changed files against them at review time. A `blocking` reference's rules\nare mandatory; `advisory` ones warn. Author your own with\n`/forge:reference create`. This is how style drift gets caught the same way doc\nand config drift do — references travel with the repo in `.forge/references/`, so\nthey bind every contributor and agent.\n\n**Two agents are *evidence-bound*; the rest are advisory.** \"Grounded by design\"\nis a property of the two auditors that gate-adjacent work depends on: the\n`doc-sync-auditor` and the `reference-auditor` must tie every finding to a\nconcrete `file:line` (or mark it `UNVERIFIABLE`), so they report real drift\nwithout hallucinating. The other agents are deliberately *not* held to that bar\nbecause their job is different: `python-quality-auditor` is a reviewer's opinion,\n`doc-gap-scanner` reports what's *absent* (which has no line to cite), and\n`python-test-author` *writes* tests from a spec. Treat the first two as detectors\nyou can trust to be literal, and the rest as proposers whose output you read.\n\n## Toolchain\n\n`uv` (env/deps) · `ruff` (lint+format) · `mypy` (types, balanced strictness) ·\n`pytest` + coverage (floor 80) · `prek` (git hooks). The plugin's own logic is\nstdlib-only and shells out to the project's `uv run …`, so hooks work even before\nthe project's environment exists.\n\n## Requirements\n\n- **Python projects only.** Every gate is built around the Python toolchain\n  above; forge has nothing to enforce on a non-Python repo.\n- **Linux and macOS only (POSIX).** The hooks invoke `python3` and the workflow\n  state is guarded by POSIX file locking (`fcntl`), so concurrent tool calls\n  can't corrupt it. Windows is not supported.\n\n## Layout\n\n```\n.claude-plugin/plugin.json   manifest\ncommands/                    the workflow commands\nagents/                      doc-sync, doc-gap-scanner, quality, security, test-author, reference auditors\nhooks/                       hooks.json + enforcement \u0026 injection scripts\nlib/                         stdlib-only core (state, fingerprint, gate, env_scan, doc_claims, decisions, references, cmdscan, hookio, status, security, versions)\nbin/                         CLI entrypoints the commands call\nreferences/                  starter style-reference library (django, cli, python-base, fastapi, library, pytest)\ntemplates/                   artifacts /forge:init scaffolds into a project\ntests/                       the plugin's own test suite (stdlib + pytest)\n```\n\nPer-project workflow state lives in `.forge/state.json`; its schema (gate\nfingerprints, the dirty set, the override trail) is documented in\n[docs/state-schema.md](docs/state-schema.md).\n\n## Developing the plugin\n\nforge holds itself to the bar it enforces. Its core logic is unit-tested and the\nchecks run under the same toolchain it ships:\n\n```bash\nuv run --group dev pytest --cov   # tests + coverage (lib/)\nuv run --group dev ruff check .   # lint\nuv run --group dev mypy lib tests bin # types\n```\n\nThe same gate runs at commit time via [prek](https://github.com/j178/prek)\n(a faster pre-commit drop-in). Install the git hooks once:\n\n```bash\nuv run --group dev prek install   # then ruff + mypy + pytest run on every commit\n```\n\nCutting a release? Follow the checklist in [docs/RELEASING.md](docs/RELEASING.md).\n\n## Installation\n\nInstall from the plugin marketplace inside Claude Code:\n\n```text\n/plugin marketplace add prabhuakshay/forge\n/plugin install forge@forge\n```\n\nThe first command registers this repo as a marketplace; the second installs the\n`forge` plugin from it (`forge@forge` is `\u003cplugin\u003e@\u003cmarketplace\u003e`). To update\nlater, re-run `/plugin marketplace update forge`.\n\nPrefer a local checkout? Clone the repo and add the directory as a plugin in\nClaude Code instead.\n\nThen run `/forge:init` in a Python project to adopt the workflow.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprabhuakshay%2Fforge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprabhuakshay%2Fforge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprabhuakshay%2Fforge/lists"}