{"id":48773998,"url":"https://github.com/wisterx-spec/agent-rails","last_synced_at":"2026-04-13T12:01:11.636Z","repository":{"id":348216261,"uuid":"1196942596","full_name":"wisterx-spec/agent-rails","owner":"wisterx-spec","description":"Description：Opinionated workflow framework for AI-assisted development — rules, skills \u0026 guardrails that keep LLMs reliable across a full project lifecycle.","archived":false,"fork":false,"pushed_at":"2026-04-13T10:19:02.000Z","size":1807,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-13T11:31:30.293Z","etag":null,"topics":["ai-agent","ai-workflow","antigravity","claude-code","codex","developer-tools","glm","llm","prompt-engineering"],"latest_commit_sha":null,"homepage":"","language":"Shell","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/wisterx-spec.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":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-03-31T07:23:56.000Z","updated_at":"2026-04-13T10:18:58.000Z","dependencies_parsed_at":null,"dependency_job_id":"67ca7eee-c108-4a62-9697-c5e55144e6c3","html_url":"https://github.com/wisterx-spec/agent-rails","commit_stats":null,"previous_names":["wisterx-spec/agent-rails"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/wisterx-spec/agent-rails","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wisterx-spec%2Fagent-rails","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wisterx-spec%2Fagent-rails/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wisterx-spec%2Fagent-rails/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wisterx-spec%2Fagent-rails/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wisterx-spec","download_url":"https://codeload.github.com/wisterx-spec/agent-rails/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wisterx-spec%2Fagent-rails/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31751705,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T09:16:15.125Z","status":"ssl_error","status_checked_at":"2026-04-13T09:16:05.023Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: 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":["ai-agent","ai-workflow","antigravity","claude-code","codex","developer-tools","glm","llm","prompt-engineering"],"created_at":"2026-04-13T12:00:51.828Z","updated_at":"2026-04-13T12:01:11.628Z","avatar_url":"https://github.com/wisterx-spec.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# agent-rails\n\n[English](README.md) | [简体中文](README_zh.md)\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n![Flow Overview](./docs/flow-overview.svg)\n\nConstraint framework for AI-assisted development — rules, skills \u0026 guardrails that keep LLMs reliable across a full project lifecycle.\n\n---\n\n## Why This Exists\n\nAI coding assistants are fast. They're also amnesiac, inconsistent, and oblivious to project history.\n\nYou describe a feature, the AI writes it, and only at review time do you realize it built the wrong thing. Or it silently broke something that was working. Or it created a third version of a component that already existed twice. Or it ignored the conventions your team spent weeks establishing.\n\nThe root problem isn't AI's coding ability — it's that **the AI has no reliable structure to operate within**. Every session starts from scratch. No guardrails, no memory, no checkpoints where a human can catch drift before it compounds.\n\nagent-rails gives the AI a framework to work inside:\n\n- **Rules** — absolute red lines, loaded at startup, always enforced\n- **Workflows** — standardized pipelines with human checkpoints at the right moments\n- **Skills** — atomic tools, lazy-loaded on demand, released after use\n- **Knowledge base** — project conventions, architecture decisions, and lessons learned that persist across sessions\n\n**Design principle: together it's a workflow, alone it's a skill.**\n\nEvery workflow is composed of independent skills. Skills can also be invoked standalone. The framework is project-agnostic — inject your specifics via `project.config.json` and it's ready.\n\n---\n\n## What Problems It Solves\n\n| Pain point | Solution |\n|------------|----------|\n| AI builds the wrong thing, you find out at the end | `requirement-clarification` spec sign-off + `proposal-review` plan review — two human gates before coding starts |\n| New features break existing ones | `impact-analysis` blast radius scan + `test-lock` baseline protection |\n| No consistent conventions | `docs/conventions.md` living doc, AI reads it before every task |\n| Wheels reinvented everywhere | Mandatory grep for existing components before creating new ones |\n| Codebase gets messier over time | `/slim` periodic cleanup + `scan-code-hygiene` pre-commit gate |\n| AI hallucinates non-existent APIs | 4-scenario anti-hallucination protocol with self-circuit-breaker |\n| Conventions pile up, stale rules never cleaned | `review-guardrails` health audit + 3-day auto-reminder + 90-day expiry detection |\n\n---\n\n## Three-Layer Architecture\n\n```\nRules (loaded at startup, always in system prompt)\n  └─ Absolute red lines. One compact file (~7KB) — no context waste.\n       ↓\nWorkflows (triggered on demand)\n  └─ Orchestration layer. Defines skill call order, conditions, and human gates.\n       ↓\nSkills (lazy-loaded)\n  └─ Atomic tools. System stores only name + path index. Agent reads full\n     content when needed, releases after use.\n```\n\n\u003e **Why this design?**\n\u003e\n\u003e Many projects stuff tens of thousands of words into the system prompt. The AI's attention gets diluted, and code quality suffers.\n\u003e\n\u003e agent-rails leverages the **lazy-load mechanism** of AI IDEs: Rules contain only absolute red lines (~7KB). Skills and Workflows exist as index entries (a few hundred tokens). The Agent reads what it needs, when it needs it. This preserves both constraint enforcement and context window efficiency.\n\n---\n\n## Requirements\n\n### Hard Prerequisites\n\nThe framework requires the AI's **file read/write tools (tool use)**. Pure chat mode won't work.\n\n- Tool use / function calling support\n- Context window ≥ 32K tokens\n\n### Recommended Models\n\n| Model | Compatibility | Notes |\n|-------|--------------|-------|\n| Premium LLMs (Claude 3.5+, GPT-4o) | Full | Framework designed for this class — best instruction-following and self-evaluation |\n| Advanced reasoning models | Full | Best for complex tasks, watch the cost |\n| GPT-4o / Gemini 1.5 Pro | Mostly works | Stable tool use, workflows may need manual triggering |\n| Local small models (≤ 13B) | Not recommended | Insufficient instruction-following, Ralph-loop unreliable |\n\n### Platform Compatibility\n\n#### Native AI Agents (Recommended)\n\nWorks out of the box for agentic environments with tool use (Antigravity IDE, Roo Code, Cursor):\n\n- Rules in `.agents/rules/` are loaded automatically\n- `/skill-name` slash commands trigger directly\n- File tools match the framework's conventions exactly\n\n```bash\n./install.sh /path/to/project\n# Open project directory in your AI assistant and start\n```\n\n#### Cursor / Continue.dev / Windsurf\n\nWorks with manual adaptation:\n\n1. Copy `.agents/rules/core.md` content into your System Prompt or `.cursorrules`\n2. Use natural language to trigger workflows (\"run the auto-dev workflow\" instead of `/auto-dev`)\n\n#### Direct API (Programmatic)\n\n1. Use `core.md` content as the system prompt\n2. Prepend the target workflow's `.md` content to the user prompt\n3. Ensure tool use is enabled with file read/write tools\n\n#### Not Applicable\n\n- Pure chat without tool use\n- GitHub Copilot (no custom rule injection)\n- Web chat interfaces (no project file access)\n\n---\n\n## 5-Minute Quickstart\n\n### 1. Install\n\n```bash\ngit clone https://github.com/wisterx-spec/agent-rails.git\n./install.sh /path/to/your-project\n```\n\n### 2. Minimal Configuration\n\nEdit `project.config.json` in your target project:\n\n```jsonc\n{\n  \"project\": { \"name\": \"your-project\" },\n  \"tech_stack\": {\n    \"frontend\": \"react+typescript\",\n    \"frontend_path\": \"frontend/src\",\n    \"backend\": \"python+fastapi\",\n    \"backend_path\": \"backend/app\",\n    \"test_path\": \"backend/tests\",\n    \"database\": \"mysql\"          // mysql | sqlite | postgres\n  },\n  \"testing\": {\n    \"local_db_url\": \"mysql+pymysql://user:pass@localhost:3306/test_db\"\n  }\n}\n```\n\nMissing fields degrade gracefully — they won't block startup.\n\n### 3. First Command\n\n```\n/requirement-clarification   ← start here for new features (recommended)\n```\n\nOr jump straight in:\n\n```\n/auto-dev implement user login with email and password\n```\n\n### 4. What to Expect\n\n```\n[CONFIG LOADED] project=your-project | frontend=react+typescript | backend=python+fastapi | db=mysql\n[MAINTENANCE DUE] Last guardrails review was 5 days ago. Consider running /review-guardrails\n\nPhase 0: Pre-read\n→ Reading conventions.md Quick Reference (2 STALE items flagged)\n→ Loading frontend-dev-guide skill\n→ Generating spec snapshot (14 lines)\n\n[SPEC LOADED] layers: frontend+backend | constraints: 4 | tokens: tailwind.config.js\n```\n\n---\n\n## Full Development Pipeline\n\n```\nUser describes requirement\n    ↓\n/requirement-clarification → Spec document → 🔴 Human confirms\n    ↓\nChoose mode: /auto-dev (AI-driven) or /dev-flow (human-driven)\n    ↓\nPre-read → Load config / conventions / decisions / domain skills\n    ↓\nPlan review → /proposal-review (non-trivial tasks) → 🔴 Human confirms\n    ↓\nExecute → Ralph-loop (Assess → Act → Verify → Log)\n    ├─ Full-stack: Frontend Component-TDD first → 🔴 UX confirmation → Backend\n    ├─ Auto-mount domain guardrails (frontend-dev-guide / db-dev-guide)\n    └─ Loop until all P0 issues resolved\n    ↓\nVerification → Structured report → 🔴 Human confirms\n    ↓\n/commit-with-affects → Standardized commit with blast radius\n    ↓\n/pr-review → PR description + 4-dimension self-check\n    ↓\n/production-release → Hygiene scan → Tests → DDL review → 🔴 Release confirmation\n    ↓\nLive\n```\n\nDetailed flowchart: [`docs/flow-overview.md`](docs/flow-overview.md) (Mermaid source) and [`docs/flow-overview.svg`](docs/flow-overview.svg).\n\n### Human Checkpoints\n\n| Gate | Location | Pass condition |\n|------|----------|----------------|\n| Spec sign-off | After requirement-clarification | User confirms spec document |\n| Plan review | auto-dev Phase 2 / dev-flow Step 3 | User replies \"confirmed\" |\n| UX evaluation | After each frontend component | User confirms issues resolved |\n| Change verification | auto-dev Phase 4 | User confirms verification report |\n| Release approval | production-release | QA + DBA + deploy approval |\n\n### Lightweight Path\n\nThese scenarios skip the proposal review to reduce confirmation fatigue:\n- Bug fix with ≤ 2 files changed\n- Pure styling / copy changes\n\n---\n\n## File Structure\n\n```\n.agents/\n  rules/\n    core.md               — Single global rules file (~7KB): bootstrap protocol,\n                            anti-hallucination, engineering red lines, domain routing,\n                            knowledge protection, experience capture, guardrail freshness\n\n  workflows/              — Orchestration layer (12 workflows)\n    requirement-clarification.md  — Structured Q\u0026A → spec sign-off\n    project-bootstrap.md          — 0→1: tech stack → page map → components → conventions\n    auto-dev.md                   — Fully automated dev (Ralph-loop, supports resume)\n    dev-flow.md                   — Human-driven dev\n    frontend-tdd.md               — Component-TDD + UX evaluation gate\n    impact-analysis.md            — Change blast radius analysis\n    hotfix.md                     — P0 production emergency fix\n    pr-review.md                  — PR description + self-review\n    slim.md                       — Project cleanup (includes guardrail review)\n    production-release.md         — Pre-release checks → tag → deploy\n    git-lifecycle.md              — Git branching and commit conventions\n    weekly-report.md              — Auto-generate weekly dev report\n\n  skills/                 — Atomic tools (25+ skills, lazy-loaded)\n    Plan review:    proposal-review/\n    Domain guides:  frontend-dev-guide/, db-dev-guide/\n    Governance:     review-guardrails/\n    Planning:       advise-tech-stack/, plan-page-map/, plan-component-hierarchy/,\n                    lock-global-conventions/\n    Testing:        generate-test-skeleton/, run-tests/, generate-test-from-impact/\n    Database:       export-db-indexes/\n    Commit:         commit-with-affects/, generate-pr-description/, pr-self-review/\n    Frontend:       frontend-ux-evaluator/, scan-frontend-quality/\n    Hygiene:        scan-code-hygiene/\n    Cleanup:        scan-orphan-components/, scan-dead-routes/, scan-unused-exports/,\n                    scan-bundle-bloat/\n    Knowledge:      sync-llm-context/, record-decision/\n\n  hooks/\n    pre-commit.sh         — Secret detection hook\n\n  scripts/\n    test_lock.py          — Test baseline tamper protection\n\ndocs/\n  INDEX.md                — Project knowledge map (AI reads first)\n  conventions.md          — Living conventions doc (maintained throughout)\n  decisions/              — Architecture Decision Records (ADR)\n  lessons/                — Project lessons learned (backend / frontend / testing)\n  flow-overview.md        — Full pipeline flowchart (Mermaid source)\n  flow-overview.svg       — Full pipeline flowchart (image)\n\nproject.config.json       — Project config (not committed)\n```\n\n---\n\n## Quick Command Reference\n\n### Workflows\n\n| Command | Purpose |\n|---------|---------|\n| `/requirement-clarification` | Clarify requirements (start here) |\n| `/project-bootstrap` | New project architecture planning |\n| `/auto-dev [spec]` | Fully automated development |\n| `/auto-dev resume` | Resume from last checkpoint |\n| `/hotfix` | P0 production emergency fix |\n| `/pr-review` | PR description + self-review |\n| `/production-release` | Pre-release checks + deploy |\n| `/slim` | Project cleanup + guardrail review |\n\n### Standalone Skills\n\n| Command | Purpose |\n|---------|---------|\n| `/proposal-review` | Plan review (human gate) |\n| `/review-guardrails` | Audit convention health (stale / conflicts / gaps) |\n| `/frontend-dev-guide` | View frontend development rules |\n| `/db-dev-guide` | View database development rules |\n| `/generate-test-skeleton --type=api\\|service\\|db\\|frontend` | Test-First skeleton |\n| `/export-db-indexes` | Database migration DDL + rollback DDL |\n| `/scan-frontend-quality` | Full frontend quality scan |\n| `/scan-code-hygiene [--scope=staged\\|all]` | Code hygiene scan |\n| `/scan-orphan-components` | Orphan component scan |\n| `/scan-dead-routes` | Dead route scan |\n| `/scan-unused-exports` | Unused export scan |\n| `/scan-bundle-bloat` | Heavy dependency scan |\n| `/sync-llm-context` | Refresh AI context map |\n| `/record-decision` | Record architecture decision |\n\n---\n\n## Typical Scenarios\n\n### New Project\n\n```\n/project-bootstrap user management system, React + FastAPI\n→ confirm tech stack → page map → component hierarchy → lock conventions\n→ /requirement-clarification [first feature]\n→ /auto-dev [confirmed spec]\n```\n\n### Taking Over an Existing Project\n\n```bash\n./install.sh /path/to/existing-project\n# fill in project.config.json\n```\n```\n/sync-llm-context          # AI scans repo, builds context map\n/scan-frontend-quality     # establish frontend quality baseline\n# then develop normally\n```\n\n### Full-Stack Feature\n\n```\n/requirement-clarification           # up to 6 clarifying questions\n→ confirm spec\n→ /auto-dev [spec]\n  → /proposal-review → human confirms plan\n  → frontend Component-TDD (test → lock → implement → UX eval → human confirms)\n  → verify UI in browser\n  → backend (API contract derived from confirmed UI)\n→ /pr-review\n→ /production-release\n```\n\n### Interrupted Mid-Feature\n\n```bash\ngit stash \u0026\u0026 git checkout -b feature/B\n# handle feature B\ngit checkout feature/A \u0026\u0026 git stash pop\n```\n```\n/auto-dev resume    # resume from tmp/.agent-session.md\n```\n\n### Periodic Maintenance\n\n```\n/slim                      # Code cleanup + guardrail health review\n/review-guardrails         # Standalone convention audit\n```\n\n---\n\n## project.config.json Key Fields\n\n```jsonc\n{\n  \"tech_stack\": {\n    \"frontend\": \"react+typescript\",\n    \"frontend_path\": \"frontend/src\",\n    \"backend\": \"python+fastapi\",\n    \"backend_path\": \"backend/app\",\n    \"test_path\": \"backend/tests\",\n    \"database\": \"mysql\",                   // mysql | sqlite | postgres\n    \"css_framework\": \"tailwind\",           // affects color convention enforcement\n    \"frontend_test_path\": \"frontend/src/__tests__\",\n    \"frontend_extensions\": [\"tsx\", \"ts\"]\n  },\n  \"testing\": {\n    \"local_db_url\": \"...\",\n    \"test_lock_script\": \".agents/scripts/test_lock.py\"\n  },\n  \"deploy\": {\n    \"tag_format\": \"v{YYYYMMDD-HHMM}-{description}\",\n    \"rollback_required\": true\n  }\n}\n```\n\nFull field reference: `project.config.example.json`\n\n---\n\n## Guardrail Freshness\n\nConventions that only grow and never shrink lead to stale rules and diluted attention. The framework has a built-in freshness cycle:\n\n```\nOn write  → Every entry must carry a date (YYYY-MM-DD)\nOn read   → Entries older than 90 days are flagged [STALE]\nOn close  → Review proposal presented, human decides: keep / update / delete\nOn start  → If last review was \u003e 3 days ago, auto-reminder for /review-guardrails\n```\n\nPositive experiences are recorded too — not just \"what not to do\" but also \"what's worth repeating.\"\n\n---\n\n## How It Constrains AI (Examples)\n\n**AI is about to create a new Modal component:**\n\n```\n[Component reuse check]\ngrep frontend/src/components/ Modal Dialog...\nFound candidates:\n  - components/common/Modal.tsx (supports title/footer/width props)\n  - components/common/DeleteConfirmModal.tsx (extends Modal)\n\n→ Reusing Modal.tsx, extending with onConfirm prop. No new component created.\n```\n\n**AI is about to commit:**\n\n```\n[scan-code-hygiene --scope=staged]\nP0: 0\nP1: 2\n  - frontend/src/pages/UserPage.tsx:47  console.log(\"debug user data\")\n  - backend/app/routers/auth.py:23      # TODO: add rate limiting\n\n→ Commit allowed. Appending: known-issues: console.log×1, TODO×1\n```\n\n**AI touches a module with an architecture decision:**\n\n```\n[Decision pre-read] docs/decisions/README.md\n1 match: jwt-auth-strategy.md (affects: backend/app/routers/auth/)\nQUICK: NEVER swap to Session Cookie | NEVER store in localStorage | NEVER TTL \u003e 2h\n\n→ NEVER constraints added to spec snapshot. Applied to all auth module changes.\n```\n\n---\n\n## Test Baseline Protection\n\n```bash\npython .agents/scripts/test_lock.py lock      # Lock after human confirms test skeleton\npython .agents/scripts/test_lock.py verify    # Verify before each test run\npython .agents/scripts/test_lock.py status    # Check current baseline\n```\n\nOnce locked, test assertions cannot be modified. If implementation breaks, fix the implementation — not the expectations.\n\n---\n\n## Knowledge Accumulation\n\nDuring development, the AI detects lessons at the end of each Ralph-loop iteration and surfaces proposals:\n\n- **`[KNOWLEDGE_UPDATE]`** — pitfalls and effective practices, written to `docs/lessons/`\n- **`[CONVENTION_PROPOSAL]`** — repeating patterns that should become conventions\n- **`[GUIDE_UPDATE]`** — experience that should be synced back to domain guide skills\n\nYou decide whether to accept each proposal. The AI never writes to knowledge files without explicit human approval.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwisterx-spec%2Fagent-rails","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwisterx-spec%2Fagent-rails","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwisterx-spec%2Fagent-rails/lists"}