{"id":42201506,"url":"https://github.com/hypernetix/code-to-spec","last_synced_at":"2026-01-27T00:26:14.923Z","repository":{"id":328408069,"uuid":"1115368688","full_name":"hypernetix/code-to-spec","owner":"hypernetix","description":"Go-lang to Rust converter","archived":false,"fork":false,"pushed_at":"2025-12-12T22:45:52.000Z","size":20,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-14T13:11:45.851Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hypernetix.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":"2025-12-12T18:51:56.000Z","updated_at":"2025-12-12T22:45:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hypernetix/code-to-spec","commit_stats":null,"previous_names":["hypernetix/code-to-spec"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/hypernetix/code-to-spec","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hypernetix%2Fcode-to-spec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hypernetix%2Fcode-to-spec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hypernetix%2Fcode-to-spec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hypernetix%2Fcode-to-spec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hypernetix","download_url":"https://codeload.github.com/hypernetix/code-to-spec/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hypernetix%2Fcode-to-spec/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28792980,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-26T21:49:50.245Z","status":"ssl_error","status_checked_at":"2026-01-26T21:48:29.455Z","response_time":59,"last_error":"SSL_read: 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":[],"created_at":"2026-01-27T00:26:14.827Z","updated_at":"2026-01-27T00:26:14.904Z","avatar_url":"https://github.com/hypernetix.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"## code-to-spec (spec-first service conversion)\n\nThis repository is a **spec-driven workflow** for converting a typical REST API microservice (like in Go-lang or Rust) into a specification:\n\n- Maintaining a **shared logic taxonomy** (Facts) that is stable across implementations.\n- Extracting the **observed behavior** of an existing service into structured specs.\n- Cross-checking and correcting those specs using multiple LLM passes.\n- Proposing upgrades/improvements to the spec before re-implementation.\n- Comparing specs and producing final **FACTS** + **BEHAVIOR** documents to feed code generation.\n\n---\n\n## Core idea: Facts Taxonomy\n\n- **Taxonomy**: see [FACTS_TAXONOMY.md](FACTS_TAXONOMY.md)\n- A **Fact** is a reusable, independently-verifiable behavior/constraint that can be referenced by multiple scenarios using the format `[FXX.YYY]`.\n- The goal is to turn “service logic” into an explicit, portable inventory that can be re-implemented in a new stack.\n\n---\n\n## Workflow (end-to-end)\n\n### Step 0) Install OpenSpec and initialize this workspace\n\nOpenSpec is the CLI used to scaffold and validate specs in this repo.\n\n**Install OpenSpec CLI (Node.js required):**\n\n```bash\nnode --version\nnpm install -g @fission-ai/openspec@latest\nopenspec --version\n```\n\n**Initialize OpenSpec in this repo:**\n\n```bash\ncd /path/to/code-to-spec\nopenspec init\n```\n\nDuring `openspec init`, select whichever AI tools you plan to use (Cursor/Windsurf/Antigravity). This will set up the `openspec/` folder if and tool-specific slash commands/agent handoffs as needed.\n\n### Step 1) Add your legacy service code as a symlink\n\nKeep this repo clean by adding the legacy codebase as a symlink (so the analysis output lives here, but the source stays in its own repo).\n\nExample:\n\n```bash\ncd /path/to/code-to-spec\nln -s /absolute/path/to/your-orig-service ./legacy-service\n```\n\nFrom here on, point the agent at `./legacy-service` (or rename it to match your conventions).\n\n### Step 1) Review and update service logic taxonomy if needed\n\nUse `FACTS_TAXONOMY.md` as the canonical categorization system for:\n- domain entities\n- scenarios\n- access control patterns\n- persistence behavior\n- outbound calls\n- background jobs\n- timeouts and limits\n- events and audit logs\n\n### Step 2) Assess existing service behavior (OpenSpec + prompt)\n\nOpen you favorite IDE with agentic mode. Your first instruction should explicitly point it at the symlinked legacy repo and the prompt to use.\n\nExample instruction:\n- “With openspec: Review my old Go-lang service in `./legacy-service` and do what I describe in `prompts/1_CODE_TO_SPEC.md`. Output `ORIG_BEHAVIOR.md` and `ORIG_FACTS.md` into a new folder for that capability.”\n\nOutput per analyzed capability/module is typically:\n- `ORIG_BEHAVIOR.md`: “what the current service does” (scenarios, primary/error paths)\n- `ORIG_FACTS.md`: reusable facts extracted from that behavior, referenced by ID in `ORIG_BEHAVIOR.md`\n\n### Step 3) Verify and correct the ORIG spec using cross-checks (multiple LLM passes)\n\nUse prompt:\n- `prompts/2_VERIFY_ORIG_SPEC.md`\n\nGoal:\n- make **only critical corrections** to `ORIG_BEHAVIOR.md` and `ORIG_FACTS.md`\n- explicitly verify, per scenario:\n  - **API role checks**\n  - **DB access checks**\n  - **license checks**\n  - **quota checks**\n  - **timeouts / limits**\n  - **events / audit logs**\n  - **outbound API communication**\n  - **concurrency / thread pooling**\n  - and whether **soft-deleted items** are included or excluded\n\n### Step 4) Propose improvements and missing scenarios (spec upgrade)\n\nUse prompt:\n- `prompts/3_SPEC_UPGRADE.md`\n\nOutput:\n- `NEW_BEHAVIOUR.md` created by copying `ORIG_BEHAVIOR.md` and applying improvements.\n- Every newly introduced step or scenario MUST be marked with a `[NEW]` prefix (so diffs are easy).\n\n### Step 5) Compare specs and prepare final FACTS/BEHAVIOR for code generation\n\nUse prompt:\n- `prompts/4_COMPARE_SPECS.md`\n\nAt this stage you have:\n- **ORIG**: audited snapshot of current system behavior\n- **NEW**: improved target behavior (still spec-only)\n\nThen:\n- compare **ORIG** vs **NEW** with special attention to changes in:\n  - APIs (paths, request/response schemas, streaming formats)\n  - scenarios (steps, conditions, fact references)\n  - **API role checks**, **DB access checks**, **license checks**, **quota checks**\n- generate `CHANGES.md`:\n  - group similar changes into chapters when a broad change affects many places\n  - keep each individual change as a separate item\n  - assign change importance: **MAJOR**, **MODERATE**, **MINOR**\n- reconcile and finalize:\n  - update facts and references to keep `[FXX.YYY]` consistent\n  - produce the final `NEW_FACTS.md` + `NEW_BEHAVIOR.md` as the source-of-truth for rewriting and/or code generation\n\n---\n\n## Notes / constraints\n\n- This workflow is **language-agnostic** in principle: any “legacy service” can be analyzed into Facts + Scenarios and then re-implemented elsewhere.\n- Whether something is “supported” must be grounded in code: if **license checks**, **quota checks**, **events**, or **audit logs** are not implemented, the spec should say so explicitly.\n- Facts are **append-only** (never renumber IDs); scenarios should reference facts via `[FXX.YYY]` rather than duplicating behavior text.\n\n---\n\n## Repo map (high-level)\n\n- **Taxonomy**: `FACTS_TAXONOMY.md`\n- **Prompts**:\n  - `prompts/1_CODE_TO_SPEC.md`\n  - `prompts/2_VERIFY_ORIG_SPEC.md`\n  - `prompts/3_SPEC_UPGRADE.md`\n  - `prompts/4_COMPARE_SPECS.md`\n- **OpenSpec guidance**: `openspec/AGENTS.md`\n- **The flow outputs**:\n  - `ORIG_BEHAVIOR.md` - original source code behavior\n  - `ORIG_FACTS.md`  - original source code facts\n  - `NEW_BEHAVIOR.md` - new source code behavior and proposals comparable with ORIG version\n  - `NEW_FACTS.md` - new source code facts and proposals comparable with ORIG version\n  - `CHANGES.md` - the difference\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhypernetix%2Fcode-to-spec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhypernetix%2Fcode-to-spec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhypernetix%2Fcode-to-spec/lists"}