{"id":50425730,"url":"https://github.com/kabatan/guardian","last_synced_at":"2026-05-31T11:00:26.973Z","repository":{"id":357820488,"uuid":"1237815107","full_name":"kabatan/guardian","owner":"kabatan","description":"Guardian-style Codex skills, agents, and profile installer for spec-driven execution.","archived":false,"fork":false,"pushed_at":"2026-05-14T11:01:40.000Z","size":43,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-14T13:06:39.606Z","etag":null,"topics":["ai-agent","automation","codex","codex-skills","developer-tools","openai-codex","spec-driven-development"],"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/kabatan.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","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-05-13T14:33:23.000Z","updated_at":"2026-05-14T11:01:05.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kabatan/guardian","commit_stats":null,"previous_names":["kabatan/guardian"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/kabatan/guardian","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kabatan%2Fguardian","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kabatan%2Fguardian/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kabatan%2Fguardian/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kabatan%2Fguardian/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kabatan","download_url":"https://codeload.github.com/kabatan/guardian/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kabatan%2Fguardian/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33728391,"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-05-31T02:00:06.040Z","response_time":95,"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":["ai-agent","automation","codex","codex-skills","developer-tools","openai-codex","spec-driven-development"],"created_at":"2026-05-31T11:00:14.369Z","updated_at":"2026-05-31T11:00:26.935Z","avatar_url":"https://github.com/kabatan.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# guardian\n\nguardian is a Codex profile pack that adds spec-driven planning, guarded execution,\nreview agents, completion checks, and session handoff workflows to your Codex environment.\n\nIt installs Codex skills, custom agents, a Guardian section in `~/.codex/AGENTS.md`,\nand required Guardian Codex config entries. It is designed to be inspectable, reversible,\nand safe to test with `--dry-run` before changing your local Codex environment.\n\nUse a tagged release for normal installation. The `main` branch may contain unreleased changes.\nThe canonical public repository URL is `https://github.com/kabatan/guardian`.\n\n## What guardian installs\n\nguardian may install or modify the following local files:\n\n- `~/.agents/skills/*` - guardian skills\n- `~/.agents/templates/guardian/*` - Guardian artifact templates\n- `~/.codex/agents/*` - guardian review agents\n- `~/.codex/AGENTS.md` - Guardian Lane rules and workflow contract\n- `~/.codex/config.toml` - Codex feature and review-agent configuration\n- `~/.codex/guardian-state.json` - install state used by uninstall and doctor\n- `~/.codex/guardian-backups/*` - timestamped backups created before changes\n\nguardian does not modify project repositories unless you explicitly ask Codex to work inside\nthem. The installer does not copy personal project trust settings, MCP settings, enabled\nplugins, history, or local evidence.\n\n## Install\n\nUse a tagged release for normal installation:\n\n```bash\ngit clone --branch v0.3.0 https://github.com/kabatan/guardian.git ~/.codex/guardian\npython ~/.codex/guardian/scripts/install.py --agents-mode merge --install-mode copy --dry-run\npython ~/.codex/guardian/scripts/install.py --agents-mode merge --install-mode copy\npython ~/.codex/guardian/scripts/doctor.py\n```\n\nRestart Codex after installation.\n\nOn Windows PowerShell, use:\n\n```powershell\ngit clone --branch v0.3.0 https://github.com/kabatan/guardian.git \"$env:USERPROFILE\\.codex\\guardian\"\npython \"$env:USERPROFILE\\.codex\\guardian\\scripts\\install.py\" --agents-mode merge --install-mode copy --dry-run\npython \"$env:USERPROFILE\\.codex\\guardian\\scripts\\install.py\" --agents-mode merge --install-mode copy\npython \"$env:USERPROFILE\\.codex\\guardian\\scripts\\doctor.py\"\n```\n\nFor most users, `merge` and `copy` are recommended:\n\n- `--agents-mode merge` preserves existing global Codex instructions and appends a marked Guardian block.\n- `--install-mode copy` keeps the installed runtime files independent from later edits in the cloned repo.\n\nRun the dry run first to preview the install without changing files:\n\n```bash\npython ~/.codex/guardian/scripts/install.py --agents-mode merge --install-mode copy --dry-run\n```\n\n## Safety Model\n\nguardian writes sidecar managed markers next to installed skills, templates, and review agents.\nIf a same-name skill, template, or review-agent file already exists and is not guardian-managed,\nthe installer stops unless you pass `--force`.\n\nWhen `--force` is used, guardian backs up the existing target before replacing it.\nBackups are stored under:\n\n```text\n~/.codex/guardian-backups/YYYYMMDD-HHMMSS/\n```\n\nThe installer records previous `features.multi_agent` and `features.goals` values in:\n\n```text\n~/.codex/guardian-state.json\n```\n\nThose recorded values can be restored during uninstall with `--restore-config`.\n\n## Advanced Options\n\nUse symlinks when you want updates in the cloned repo to be reflected immediately:\n\n```bash\npython ~/.codex/guardian/scripts/install.py --agents-mode merge --install-mode link\n```\n\n`--install-mode link` can propagate later edits, `git pull` changes, or local mistakes in the\ncloned repo directly into your active Codex runtime. Use it only if you intentionally want that\nlive-update behavior. For most users, `--install-mode copy` is recommended.\n\nReplace your global `AGENTS.md` only when you want guardian to fully manage it:\n\n```bash\npython ~/.codex/guardian/scripts/install.py --agents-mode replace --install-mode copy\n```\n\n`--agents-mode replace` overwrites your global Codex instructions after creating a backup.\nUse it only if you want guardian to fully manage your global `AGENTS.md`.\nFor most users, `--agents-mode merge` is recommended.\n\nOther install options:\n\n```bash\npython scripts/install.py --no-config\npython scripts/install.py --no-agents\npython scripts/install.py --no-skills\npython scripts/install.py --backup-dir /path/to/backups\npython scripts/install.py --version\n```\n\n## Update\n\nIf you installed from a tagged release, update by checking out a newer release and reinstalling:\n\n```bash\ncd ~/.codex/guardian\ngit fetch --tags\ngit checkout \u003cnew-version\u003e\npython scripts/install.py --agents-mode merge --install-mode copy --dry-run\npython scripts/install.py --agents-mode merge --install-mode copy\npython scripts/doctor.py\n```\n\nAvoid installing directly from `main` unless you want development changes.\n\n## Uninstall And Rollback\n\nRemove guardian-managed files and the marked Guardian `AGENTS.md` block:\n\n```bash\npython ~/.codex/guardian/scripts/uninstall.py\n```\n\nRestore recorded Codex feature flag values while uninstalling:\n\n```bash\npython ~/.codex/guardian/scripts/uninstall.py --restore-config\n```\n\nPreview uninstall without changing files:\n\n```bash\npython ~/.codex/guardian/scripts/uninstall.py --dry-run\n```\n\nThe uninstaller removes only sidecar-marker-managed skills, templates, and review agents.\nUnmarked same-name files are preserved. Backups are kept.\n\nTo manually roll back, restore `AGENTS.md`, `config.toml`, or replaced skill/agent paths from\nthe latest backup directory under `~/.codex/guardian-backups/`.\n\n## Doctor\n\nRun doctor after install or update:\n\n```bash\npython ~/.codex/guardian/scripts/doctor.py\n```\n\nDoctor checks installed skills, templates, review agents, managed markers, broken symlinks,\nthe marked Guardian `AGENTS.md` block, `config.toml`, install state, version, and backup\ndirectory.\n\n## Requirements\n\n- Codex CLI with skills support\n- Python 3.9+\n- Python 3.11+ uses built-in TOML parsing\n- Python 3.9 or 3.10 requires `tomli` for TOML parsing\n- Git\n- Access to the configured reviewer model names in `agents/*.toml`, or a Codex runtime fallback\n  that can run equivalent reviewer agents\n\nTested on:\n\n- Linux: GitHub Actions workflow covers Ubuntu across Python 3.9, 3.10, 3.11, and 3.12 after the workflow is run.\n- macOS: GitHub Actions workflow covers macOS across Python 3.9, 3.10, 3.11, and 3.12 after the workflow is run.\n- Windows: GitHub Actions workflow covers Windows across Python 3.9, 3.10, 3.11, and 3.12 after the workflow is run; local script and unit-test development also happens on Windows.\n\nCompatibility notes:\n\n- Codex runtime support for skills and custom agents is required. TOML files alone do not prove\n  reviewer agent runtime availability.\n- Reviewer agent registration depends on the Codex runtime. If a current session does not expose\n  newly installed custom agents, restart Codex and run `doctor.py` again.\n- Reviewer model access depends on your Codex account and configured runtime. If a configured reviewer\n  model is unavailable, use a Codex-supported fallback model or edit the local agent TOML files\n  before reinstalling.\n- Known limitations: GitHub Actions improves OS and Python coverage, but it does not certify every\n  Codex runtime, model entitlement, shell, filesystem, symlink, WSL, or local permission setup.\n\n## Minimal Example\n\nAfter installing guardian, ask Codex to use Guardian Lane for work that needs a spec, review, or\nstrong completion claim. A minimal flow is:\n\n1. \"Use Guardian Lane for this change. First create a Base Spec from my requirements.\"\n2. Review the Base Spec and answer any blocking questions.\n3. Ask Codex to create a Plan against the approved R-IDs and review checkpoints.\n4. Approve the Plan, then let Codex implement only the admitted items.\n5. Run the Guardian reviewers at the required checkpoints.\n6. Close with a CLOSURE report that cites fresh verification evidence.\n\nSee [docs/glossary.md](docs/glossary.md) for the Guardian terms used in this flow.\n\n## Reference Docs\n\n- [docs/codex-guardian-final-spec.md](docs/codex-guardian-final-spec.md) is the detailed target design.\n- [docs/docs-lifecycle.md](docs/docs-lifecycle.md) defines how AI-created markdown should be classified and retired.\n\nThese docs are reference material, not per-task Base Specs or Plans.\n\n## Guardian Lane\n\nUse Guardian Lane for long-running, spec-heavy, review-sensitive, data/security-sensitive,\npublic API, persistence, algorithmic, source-fidelity-sensitive, or strong readiness,\nverified, or complete claims.\n\nThe core flow is:\n\n1. Convert Original Source into an Approved Base Spec.\n2. Plan against R-IDs, MECHs, blockers, acceptance, verification, allowed claims, and review checkpoints.\n3. Execute admitted plans with fresh evidence.\n4. Use reviewers at boundary checkpoints.\n5. Make only claims supported by exact evidence.\n\nDefault Lane remains available for narrow routine work with scoped claims.\n\n## Release Trust And Verification\n\nUse tag pinning for normal installs:\n\n```bash\ngit clone --branch v0.3.0 https://github.com/kabatan/guardian.git ~/.codex/guardian\n```\n\nBefore installing or updating, run the installer with `--dry-run` and review the paths listed in\nthe output. guardian may modify only the files listed in \"What guardian installs\", and it records\nbackups under `~/.codex/guardian-backups/` for rollback.\n\nCurrent releases do not publish a signed tag guarantee or checksum file. Verify the GitHub release,\ntag, and commit according to your own trust requirements before installing.\n\n## Disclaimer\n\nguardian is an independent project and is not affiliated with OpenAI.\nIt changes local Codex configuration files, so review the installer and run `--dry-run`\nbefore installing if you are unsure.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkabatan%2Fguardian","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkabatan%2Fguardian","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkabatan%2Fguardian/lists"}