{"id":47696886,"url":"https://github.com/ajithnow/reopenspec","last_synced_at":"2026-04-03T20:01:17.117Z","repository":{"id":347518920,"uuid":"1194191248","full_name":"ajithnow/reopenspec","owner":"ajithnow","description":"Spec-driven development with a deterministic code snapshot. ReOpenSpec is a small CLI (reo) that scans your repo into arch-baseline.json, compares each feature’s api-contracts.json to that baseline (drift), and injects short IDE rules so agents ground structure and contracts in those files.","archived":false,"fork":false,"pushed_at":"2026-03-30T15:20:43.000Z","size":665,"stargazers_count":2,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T03:09:12.118Z","etag":null,"topics":["openspec","sdd","spec-driven","spec-driven-development"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/ajithnow.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-03-28T03:01:28.000Z","updated_at":"2026-03-30T15:21:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ajithnow/reopenspec","commit_stats":null,"previous_names":["ajithnow/reopenspec"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ajithnow/reopenspec","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajithnow%2Freopenspec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajithnow%2Freopenspec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajithnow%2Freopenspec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajithnow%2Freopenspec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ajithnow","download_url":"https://codeload.github.com/ajithnow/reopenspec/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajithnow%2Freopenspec/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31374051,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T17:53:18.093Z","status":"ssl_error","status_checked_at":"2026-04-03T17:53:17.617Z","response_time":107,"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":["openspec","sdd","spec-driven","spec-driven-development"],"created_at":"2026-04-02T16:30:49.927Z","updated_at":"2026-04-03T20:01:17.031Z","avatar_url":"https://github.com/ajithnow.png","language":"TypeScript","readme":"# ReOpenSpec\n\n**Spec-driven architecture baseline, drift checks, and context-aware IDE workflow injection.** \n\nReOpenSpec an agentic workflow engine that scans your repository into `arch-baseline.json`, compares each feature’s `api-contracts.json` to that baseline (drift), and injects tailored IDE rules natively based on your environment (Cursor, Windsurf, or Roo). It grounds AI agents in firm architectural contracts and drastically reduces AI context pollution.\n\nIt sits in the same problem space as [OpenSpec](https://github.com/Fission-AI/OpenSpec) (specs in git, AI-assisted workflows) but introduces **native multi-IDE profile detection**, **categorized `.mdc` rule injection**, and **multi-language AST-grounded drift tracking**.\n\n## Repository layout (`docs` / `specs` / `changes`)\n\nReOpenSpec assumes (and `reo init` creates) a strict, traceable three-tier architecture at the project root:\n\n| Path | Role |\n|------|------|\n| **`reopenspec/docs/`** | Architecture narratives, ADRs, runbooks, team conventions — high-level context that is **not** the live behavioral contract. |\n| **`reopenspec/specs/`** | Domain behavior, scenarios, and **`api-contracts.json`** — the **source of truth**, cross-checked against code via deterministic drift detection. |\n| **`reopenspec/changes/active/`** | In-flight work: one folder per story, task, or bug (e.g. `task-azure-1234`) managed by a strict `change.yaml` scaffold and tracking `/reo-plan` deltas. |\n| **`reopenspec/changes/completed/`** | Done work: Moved here automatically with a date prefix upon `/reo-completed` to cleanly archive context without polluting the agent's main memory. |\n\nSee **[`reopenspec/docs/reopenspec-model.md`](reopenspec/docs/reopenspec-model.md)** for the full architectural model.\n\n## Requirements\n\n- **Node.js 20+**\n\n## Install\n\n```bash\nnpm install -g reopenspec\n```\n\nCheck: `reo --help`\n\n## Quick start\n\n### 1. Initialize the Workspace\n\nIn your project root:\n\n```bash\nreo init\n```\n\nThis acts as your unified bootstrap. It creates the repository layout, writes `reopenspec.json`, runs an initial baseline scan, **auto-detects your IDE profile** (Cursor, Roo, or Windsurf), and strictly injects categorized `.mdc` rules and slash-command templates (`.cursor/commands/`, `.windsurf/`, etc.) based on your primary language and IDE. \n\n*(Use `reo init --skip-workflow` to only generate the baseline and config.)*\n\n### 2. The 5-Step Traceable Feature Flow\n\nReOpenSpec enforces a predictable lifecycle for AI coding agents:\n1. **`reo init`**: Establishes the workspace and syncs agent rule profiles.\n2. **`/reo-blueprint`**: Generates architecture specs based on the baseline and contextually activates IDE rules.\n3. **`/reo-plan`**: Connects via MCPs (Jira/Azure/Figma), parses dependencies, and provisions a heavily-traced scaffold under `reopenspec/changes/active/` driven by a concrete `change.yaml`.\n4. **`/reo-proceed-plan`**: Reads the active change folder and executes the feature implementation in isolated steps.\n5. **`/reo-completed`** (Human-run): Evaluates the proceed-plan work, proposes updates to `reopenspec/specs/`, and safely archives the work into `changes/completed/YYYY-MM-DD/` to lock the spec and erase short-term memory pollution.\n\n### 3. Track Contracts \u0026 Compute Drift\n\nPoint contracts at real exports inside `reopenspec/specs/\u003cfeature\u003e/api-contracts.json`:\n```json\n{\n  \"id\": \"user-login\",\n  \"mapsTo\": { \"file\": \"src/services/LoginService.ts\", \"symbol\": \"LoginService\", \"kind\": \"export.class\" }\n}\n```\n\nThen synchronize and calculate drift:\n\n```bash\nreo sync --verbose\n```\n*(Outputs to `reopenspec/specs/.meta/arch-baseline.json` and `drift-report.json`)*.\n\n---\n\n## Commands\n\n| Command                           | Purpose                                                                                                                                   |\n| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |\n| `reo init`                        | First-time: dirs, config, baseline scan, dynamic IDE profile detection, and contextual rule/workflow injection.                           |\n| `reo init --skip-workflow`        | Core initialization without injecting `.mdc` rules or IDE templates.                                                                      |\n| `reo sync`                        | Full workspace scan + structural drift report computation against active contracts.                                                       |\n| `reo scan`                        | Generate and write `arch-baseline.json` only.                                                                                             |\n| `reo drift` / `reo diff`          | Check codebase drift solely against `reopenspec/specs/*/api-contracts.json`.                                                              |\n| `reo doctor`                      | Checks workspace health (validates config, directories, and spec contract references).                                                    |\n| `reo spec new \u003cslug\u003e`             | Scaffold a fresh domain feature folder + `.spec-meta.json`.                                                                               |\n| `reo inject`                      | Hard force re-apply of the latest dynamic categorised IDE rules.                                                                          |\n| `reo config`                      | Show or create your `reopenspec.json`.                                                                                                    |\n| `reo status`                      | Prints config paths + high-level baseline/drift summary.                                                                                  |\n| `reo hooks install` / `uninstall` | Git pre-commit hook (`reo sync`) to ensure contracts are strictly enforced on commit.                                                     |\n\nRun `reo \u003ccommand\u003e --help` for flags. *(Tip: Use `--verbose` on `reo scan` or `reo sync` for detailed node-extraction logs).*\n\n## Languages\n\nReOpenSpec organically traverses multi-language workspaces using a unified Parser Adapter pattern.\n\n- **TypeScript / TSX** — via [ast-grep](https://ast-grep.github.io/) (`@ast-grep/napi`): true AST parsing for exports and imports.\n- **C# / .NET** — heuristic scan (namespaces, classes, interfaces, records, functions, and `using` module specs).\n- **Python** — heuristic scan (classes, `def` functions, and aliased imports).\n- **PHP** — heuristic scan (namespaces, classes, interfaces, traits, functions, and `use` aliases).\n- **Dart / Flutter** — heuristic scan (imports + top-level declarations); `build/` and `.dart_tool/` are ignored.\n\n## Under the Hood: The Rules Engine\n\nReOpenSpec's secret weapon is how it handles Context Pollution. During `reo init` and `reo inject`, the CLI doesn't just dump 5,000 lines of prompt into your agents. It detects the active profile (e.g. PHP + React) and strategically copies `.mdc` standard files into place, defining explicit activation triggers (e.g. \"always-on\" vs. \"agent-requested\"). \n\n## Configuration\n\n`reopenspec.json` at the repo root (or `reopenspec/specs/.meta/reopenspec.json`) sets your project directives:\n- `baselinePath`\n- `driftReportPath`\n- `specsDir`\n- `strictUncovered`\n\n## VS Code\n\nA minimal extension lives under `editors/vscode/` (config editor + run sync). Build it with `npm run vscode:compile` from the repo.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fajithnow%2Freopenspec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fajithnow%2Freopenspec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fajithnow%2Freopenspec/lists"}