{"id":51862153,"url":"https://github.com/majiayu000/specrail","last_synced_at":"2026-07-24T09:02:22.309Z","repository":{"id":366521642,"uuid":"1275932091","full_name":"majiayu000/specrail","owner":"majiayu000","description":"Spec-first rails for agent-assisted repository workflows.","archived":false,"fork":false,"pushed_at":"2026-07-19T06:34:04.000Z","size":931,"stargazers_count":23,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-19T08:13:15.398Z","etag":null,"topics":["agent-workflows","ai-agents","ci","code-review","developer-tools","github","open-source","repository-ops","spec-first","workflow-automation"],"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/majiayu000.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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-21T10:24:54.000Z","updated_at":"2026-07-19T06:10:59.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/majiayu000/specrail","commit_stats":null,"previous_names":["majiayu000/specrail"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/majiayu000/specrail","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/majiayu000%2Fspecrail","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/majiayu000%2Fspecrail/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/majiayu000%2Fspecrail/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/majiayu000%2Fspecrail/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/majiayu000","download_url":"https://codeload.github.com/majiayu000/specrail/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/majiayu000%2Fspecrail/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35835401,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-24T02:00:07.870Z","response_time":62,"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-workflows","ai-agents","ci","code-review","developer-tools","github","open-source","repository-ops","spec-first","workflow-automation"],"created_at":"2026-07-24T09:02:21.554Z","updated_at":"2026-07-24T09:02:22.299Z","avatar_url":"https://github.com/majiayu000.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SpecRail\n\n[![workflow-check](https://github.com/majiayu000/specrail/actions/workflows/workflow-check.yml/badge.svg)](https://github.com/majiayu000/specrail/actions/workflows/workflow-check.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Release](https://img.shields.io/github/v/release/majiayu000/specrail?include_prereleases\u0026label=release)](https://github.com/majiayu000/specrail/releases)\n\nAgent-facing workflow pack for issue-first, spec-first, AI-assisted repository operations.\n\nSpecRail is not a bot and not an agent runtime. It is a portable process\nlibrary: state machines, templates, schemas, review gates, and deterministic\nchecks that a repository can adopt before adding automation.\n\nSpecRail's primary consumer is a code agent such as Codex, Claude Code, or a\nrepo-local automation agent. Humans maintain the policy, review final decisions,\nand own gates such as readiness labels, security decisions, approval, merge, and\nrelease.\n\n## Goals\n\n- Make repository work explicit as a state machine.\n- Keep GitHub issues and pull requests as durable state.\n- Require specs for ambiguous or product-facing changes.\n- Let agents produce review and triage artifacts without final authority.\n- Keep human maintainers as the final review and merge gate.\n\n## Non-Goals\n\n- No automatic merge.\n- No security disclosure handling in public issues.\n- No cloud control plane.\n- No direct dependency on VibeGuard hooks or runtime.\n- No assumption that every repository uses AI agents.\n\n## MVP Contents\n\n```text\nLICENSE                # MIT license\nCHANGELOG.md           # release notes\nworkflow.yaml          # workflow metadata and adoption policy\nstates.yaml            # canonical issue/spec/PR state machine\nlabels.yaml            # recommended label taxonomy\ndocs/                  # adoption matrix and user-facing workflow docs\ntemplates/             # issue, spec, and PR templates\nlocales/               # localized human-facing evaluator messages\nintegrations/          # optional adapters to agent orchestration workflows\nskills/                # agent workflow entrypoints, including Codex-compatible skills\nskills-lock.json       # repo-distributed skill lockfile\ntools/                 # optional local installation helpers\nschemas/               # machine-readable artifact contracts\nexamples/adoptions/    # machine-readable adoption evidence fixtures\nexamples/fixtures/     # deterministic gate benchmark fixtures\nreview/                # agent-first and human-final review guides\npolicies/              # security and maintainer escalation policy\nchecks/check_workflow.py\nchecks/route_gate.py\nchecks/github_issue_evidence.py\nchecks/github_pr_evidence.py\nchecks/review_json_gate.py\nchecks/runtime_ledger_gate.py\nchecks/closure_audit.py\n.github/workflows/workflow-check.yml\n```\n\n## Quick Start\n\nValidate the pack locally:\n\n```sh\ngit clone https://github.com/majiayu000/specrail.git\ncd specrail\npython3 checks/check_workflow.py --repo .\n```\n\nValidate a spec packet:\n\n```sh\npython3 checks/check_workflow.py --repo . --spec-dir specs/GH1\n```\n\nValidate every `specs/GH\u003cnumber\u003e` packet:\n\n```sh\npython3 checks/check_workflow.py --repo . --all-specs\n```\n\nThe all-specs scan uses `workflow.yaml`'s `artifacts.spec_packet` template, so\nadopted repositories may keep packets under paths such as `docs/specs/GH1`.\n\nEvaluate whether an agent may take the next workflow action from local evidence:\n\n```sh\npython3 checks/route_gate.py --repo . --route write_spec --issue 123 --state ready_to_spec --json\npython3 checks/route_gate.py --repo . --route implement --issue 123 --state ready_to_implement --json\n```\n\nCollect read-only GitHub issue evidence before running the route gate:\n\n```sh\npython3 checks/github_issue_evidence.py --repo . --github-repo OWNER/REPO --issue 123 --json \u003e issue-evidence.json\npython3 checks/route_gate.py --repo . --route write_spec --issue 123 --evidence issue-evidence.json --json\n```\n\n`checks/github_issue_evidence.py` is read-only. It uses `gh issue view` for issue\nstate and labels. For a trusted `ready_to_implement` issue in a repository with\na sensitive registry, it first queries the GitHub default-base identity, checks\nthat identity against the local `origin` ref and symbolic `origin/HEAD`, and\nclassifies the approved tech manifest from that exact base. A non-sensitive\nplan stops there. A sensitive plan additionally queries the current approval\nlabel and latest matching label event through GraphQL, then uses the REST\nassociated-PR endpoint to prove each approved spec source came from exactly one\nmerged default-branch PR.\n\nThe adapter does not write labels, comments, issues, or PRs. Body hints remain\nuntrusted. Missing or non-symbolic `origin/HEAD`, default-base drift, an empty\ncompleted planned-path list, incomplete latest approval actor/timestamp, missing\nmerged-spec provenance, or approved-spec content drift fails closed. Ordinary,\nclassified non-sensitive, and classified sensitive outputs conform to\n`schemas/issue_evidence.schema.json`. Artifact paths are rendered from the\nselected repo's `workflow.yaml`.\n\nEvaluate whether PR merge evidence is complete before a maintainer merges:\n\n```sh\npython3 checks/github_pr_evidence.py --github-repo OWNER/REPO --pr 123 --json \u003e pr-evidence.json\npython3 checks/pr_gate.py --repo . --evidence pr-evidence.json --json\n```\n\n`checks/github_pr_evidence.py` is a read-only collector for GitHub CLI output.\n`checks/pr_gate.py` owns the offline merge-readiness decision.\n\nAfter a merge, audit that the allowed gate query, merge dispatch, and confirmed\nremote merge all refer to the final head and satisfy `gate \u003c dispatch \u003c= merged`:\n\n```sh\npython3 checks/closure_audit.py --repo . --evidence closure-evidence.json --json\n```\n\nThe closure audit is offline and advisory-only. It performs no GitHub writes,\nreturns `0` for a compliant chain, `1` for a schema-valid violation, and `2`\nfor malformed input. Violations include a stable `required_follow_up` payload\nthat a consumer may persist or route without granting the audit write access.\n\nValidate an optional local runtime checkpoint for long agent runs:\n\n```sh\npython3 checks/runtime_ledger_gate.py --checkpoint .specrail/runtime/current.json --json\n```\n\nRuntime checkpoints are handoff aids for bounded agent tranches. They do not\nreplace GitHub issues, pull requests, labels, reviews, branches, or SpecRail\nspec packets as durable workflow state. For checkpoint contracts, the schema is\nthe structure authority and `checks/runtime_ledger_gate.py` is the behavior\nauthority; see [`SPEC.md`](SPEC.md#runtime-checkpoint-contract-authority).\n\nValidate an advisory review artifact against a unified diff:\n\n```sh\npython3 checks/review_json_gate.py --repo . --review artifacts/review/pr-123.json --diff pr.diff --json\n```\n\nReview artifacts are advisory evidence only. They do not grant final approval or\nmerge authority. Their body must include `## Summary` and `## Verdict`; inline\ncomments may use validated multi-line ranges and RIGHT-side suggestion blocks.\n\nEvaluate a spec packet and adoption smoke evidence:\n\n```sh\npython3 evaluate.py --repo . --spec-dir specs/GH1 --format json\n```\n\nInspect the recorded real-repo adoption signals:\n\n- [`docs/ADOPTION_MATRIX.md`](docs/ADOPTION_MATRIX.md)\n- [`examples/adoptions/matrix.json`](examples/adoptions/matrix.json)\n\nThe matrix currently records `rclean`, `litellm-rs`, and\n`Claude-Code-Monitor` / `claude-hub` as pilot evidence at different maturity\nlevels. `evaluate.py` validates the required matrix records and local\nSpecRail evidence paths.\n\nFor long issue or PR queues, agents may also keep an optional local runtime\ncheckpoint based on [`templates/tranche_checkpoint.md`](templates/tranche_checkpoint.md).\nThe checkpoint is for context-budget and handoff control only; the canonical\nworkflow truth remains the repository and GitHub artifacts above.\n\nGate benchmark fixtures live in `examples/fixtures/`. They are deterministic\ntest inputs for route, PR, and review gates, not claims about current GitHub\nstate or adoption level.\n\n## Autonomous SpecRail Mode\n\nAn agent should switch complex work into SpecRail mode before broad\nimplementation, even if the repository has not adopted the full pack. Typical\ntriggers are product-facing changes, architecture changes, cross-module work,\npublic API changes, workflow-policy changes, PR merge-readiness checks, CI\ndiagnosis with unclear ownership, or ambiguous requests whose done-when is not\nyet testable.\n\nSpecRail mode means the work uses the actual SpecRail structure: search first,\nchoose a route, produce or request durable product/tech/task artifacts, preserve\nhuman gates, and run deterministic verification. If the repository has not\nadopted the pack, use its existing specs/plan/docs location to carry that\nstructure. Do not silently copy this pack into a repository, install local\nskills, create remote issues or PRs, add labels, approve, merge, or bypass\nmaintainers. Those actions require an explicit user request.\n\n## Agent-First Setup\n\nFor setup, installation, update, verification, or adoption, ask the agent to use\n`skills/specrail-install/SKILL.md`. The skill is the agent-facing entrypoint and\ndecides whether to run a doctor check, install local Codex skills, update global\nguidance, or plan repository adoption. The CLI commands below are deterministic\nhelpers used by the skill, not the primary interface humans need to memorize.\n\n## Optional Local Codex Skill Install\n\nLocal installation is optional. It is only for users who explicitly want this\ncheckout's SpecRail skills available from the local Codex skill directory. It is\nnot required for adopting SpecRail in a repository.\n\nPreview the install plan without writing files:\n\n```sh\npython3 tools/install_codex_skills.py --repo .\n```\n\nApply the install after reviewing the plan:\n\n```sh\npython3 tools/install_codex_skills.py --repo . --apply\n```\n\nThe installer validates `skills-lock.json`, syncs only the locked skill\ndirectories, writes to `$CODEX_HOME/skills` when `CODEX_HOME` is set or\n`~/.codex/skills` otherwise, and refuses unsafe targets that would overwrite the\nsource skills. A new Codex session may be needed before newly installed skills\nare visible.\n\n## Repository Adoption\n\nUse the pack as a repository workflow contract. For a normal repository, copy\nthe pack files into the target repo and keep that repo's product docs intact:\n\n```sh\ncp -R templates schemas review policies checks skills tools examples docs .github /path/to/your-repo/\ncp AGENT_USAGE.md SPEC.md CHANGELOG.md workflow.yaml states.yaml labels.yaml /path/to/your-repo/\ncp skills-lock.json /path/to/your-repo/\n```\n\nKeep the consumer repository's own `README.md` and `LICENSE` unless the\nmaintainer explicitly wants to replace them.\n\nThe workflow checker validates the copied SpecRail schema and template set by\nexplicit ownership. Consumer-owned files may coexist under `schemas/` and\n`templates/` without being treated as SpecRail assets.\n\nIf the consumer repository does not already have an `AGENTS.md`, add a short\nentrypoint that points agents at the copied SpecRail contract:\n\n```md\n# AGENTS.md\n\nRead `AGENT_USAGE.md`, `workflow.yaml`, `states.yaml`, `labels.yaml`, and\n`skills/specrail-workflow/SKILL.md` before creating issues, specs, PRs, reviews,\nor handoffs. Keep automation in dry-run/advisory mode unless a maintainer\nexplicitly authorizes otherwise.\n```\n\nIf the consumer repository already has an `AGENTS.md`, merge the SpecRail\nentrypoint into the existing instructions instead of replacing local policy.\n\nThen ask your agent to read:\n\n```text\nAGENTS.md\nworkflow.yaml\nstates.yaml\nlabels.yaml\nAGENT_USAGE.md\nskills/specrail-workflow/SKILL.md\nskills-lock.json\n```\n\n## Adoption Path\n\n1. Read [`AGENT_USAGE.md`](AGENT_USAGE.md) to understand how an agent should consume the pack.\n2. Choose an adoption mode:\n   - copy files into the repo when you want the simplest local contract\n   - use a submodule when you want to track SpecRail separately\n   - use a package or generated overlay only after the copied workflow is stable\n3. Add or merge the `AGENTS.md` entrypoint above.\n4. Run `python3 checks/check_workflow.py --repo .`.\n5. Run `python3 checks/check_workflow.py --repo . --all-specs` after adding spec packets.\n6. Add the GitHub Action from `.github/workflows/workflow-check.yml`.\n7. Start with dry-run checks only.\n8. Add label/comment automation only after maintainers trust the signal.\n\n## Plan\n\nSee [`PLAN.md`](PLAN.md) for the agent-first product direction, current limits,\nand the roadmap from templates to deterministic evaluator to automation.\n\n## Release\n\nCurrent release notes live in [`CHANGELOG.md`](CHANGELOG.md). SpecRail v0.2.1\nadds adoption matrix evidence for real pilot repositories and hardens evaluator\nand CI coverage while remaining intentionally advisory: deterministic checks\nfirst, automation later.\n\n## Core Principle\n\nAgents may suggest, draft, review, and diagnose. Humans own readiness labels,\nsecurity decisions, final approval, merge, and release.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmajiayu000%2Fspecrail","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmajiayu000%2Fspecrail","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmajiayu000%2Fspecrail/lists"}