Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/freshtechbro/specatlas

SpecAtlas is a CLI-first product reverse-engineering and clean-room planning system.
https://github.com/freshtechbro/specatlas

Last synced: about 1 month ago
JSON representation

SpecAtlas is a CLI-first product reverse-engineering and clean-room planning system.

Awesome Lists containing this project

README 

          
# SpecAtlas



SpecAtlas is a CLI-first product intelligence and clean-room planning workspace. It turns safe product, repository, web, API, artifact, and worker evidence into a structured SpecAtlas package: 30 decomposition maps, reports, graphs, evidence ledgers, clean-room handoffs, and agent task plans.



The Rust core owns product behavior. Workers are invoked by the core as subprocess adapters; web, desktop, server, and MCP surfaces either call the core or read generated packages through shared schemas and contracts.



## Contents



| Start | Product | Run | Surfaces | Project |

|---|---|---|---|---|

| [Quick start](#quick-start) | [What SpecAtlas is](#what-specatlas-is) | [CLI workflows](#cli-workflows) | [Web workbench](#web-workbench) | [Repository layout](#repository-layout) |

| [Prerequisites](#prerequisites) | [What SpecAtlas does](#what-specatlas-does) | [Common commands](#common-commands) | [Desktop shell](#desktop-shell) | [Generated package layout](#generated-package-layout) |

| [Install](#install) | [What SpecAtlas does not do](#what-specatlas-does-not-do) | [Server and MCP](#server-and-mcp) | [Workers and plugins](#workers-and-plugins) | [Documentation map](#documentation-map) |

| [Quality gates](#quality-gates) | [Architecture](#architecture) | [Package validation](#package-validation) | [Safety model](#safety-model) | [Agent notes](#agent-notes) |



## Quick start



```bash

npm install

cargo run -q -p specatlas-cli -- --help

cargo run -q -p specatlas-cli -- study WebPilot target/specatlas-routes/study

npm --prefix apps/web run dev

```



Open the web workbench at `http://127.0.0.1:5173/?manifest=/sample-package/specatlas-package-manifest.json`, or upload a generated package directory in the browser.



## What SpecAtlas is



SpecAtlas is a local-first system for converting authorized evidence into a buildable clean-room implementation package. It supports two main operating modes:



- Product teardown clean-room planning: discover product structure, competitive context, features, architecture, risks, and implementation tasks without copying protected expression.

- Instrumentation mode: normalize worker output from safe fixtures, imports, static analyzers, browser observations, and metadata tools into package evidence.



SpecAtlas is designed for repeatable package generation, agent handoff, safety review, and package inspection rather than ad hoc prose reports.



## What SpecAtlas does



- Runs CLI workflows for study, research, repository analysis, static analysis, URL analysis, web crawl, API inference, artifact import, decomposition, clean-room specs, agent plans, and instrumentation.

- Produces 30 canonical decomposition maps plus reports, graphs, risk records, policy decisions, agent handoffs, and task DAGs.

- Enforces Rust-core policy and sanitization before writing agent-facing reports and handoffs.

- Runs Python and Node workers behind stdio adapter contracts.

- Provides a read-only React workbench for package review.

- Provides a Tauri desktop shell around the web workbench and local CLI workflows.

- Provides server and MCP boundaries for collaboration metadata, JSON-RPC resources, and safe package access.



## What SpecAtlas does not do



- It does not copy proprietary assets, hidden implementation, private code, or blocked evidence into agent outputs.

- It does not treat web, desktop, workers, or server code as product logic owners.

- It does not silently fake external analyzer success. Missing tools must produce unavailable diagnostics.

- It does not expose blocked evidence content through reports, web previews, MCP resources, or agent handoffs.

- It does not claim hosted persistence is verified unless the configured server boundary and quality gates have actually run.



## Prerequisites



- Rust >= 1.78, edition 2021.

- Node >= 20.

- Python >= 3.11.

- Optional `just` for command aliases.

- Tauri platform prerequisites when building the desktop app.

- Optional `cargo llvm-cov` for the final 97 percent coverage gate.



## Install



```bash

npm install

cargo metadata --format-version 1 --no-deps

python3 -m compileall -q workers

```



Rust dependencies are resolved by Cargo. Node workspaces are `apps/web` and `apps/desktop`. Python worker tests use the standard library test runner in this repository.



## Common commands



```bash

# Rust

cargo fmt --all -- --check

cargo clippy --all-targets --all-features -- -D warnings

cargo test --all-targets --all-features

cargo llvm-cov --workspace --all-targets --all-features --fail-under-lines 97 --summary-only -j 1



# Root JS, Python, web

npm run lint

npm run typecheck

npm run test

npm run build

npm run check



# Smoke and final gates

npm run desktop:smoke

npm run package:smoke

npm run quality:final



# Optional just aliases

just check

just schema-validate

```



## CLI workflows



Use the workspace binary through Cargo while developing:



```bash

cargo run -q -p specatlas-cli -- 

```



Global flags parsed by the CLI:



```text

--output 

--format json|text

--json

--mode 

--profile 

--authorization 

--policy 

--evidence-required

--no-proprietary-assets

--no-copied-copy

--product-description 

--example-url 

--seed-repo 

--stage 

--discovery-import 

```



Implemented command surfaces:



```bash

cargo run -q -p specatlas-cli -- init specatlas-project

cargo run -q -p specatlas-cli -- identify  specatlas-project

cargo run -q -p specatlas-cli -- teardown  --product-description "" --example-url  --discovery-import  --output target/specatlas-routes/teardown

cargo run -q -p specatlas-cli -- study  --output target/specatlas-routes/study

cargo run -q -p specatlas-cli -- research external  --output target/specatlas-routes/research

cargo run -q -p specatlas-cli -- find-repos  --output target/specatlas-routes/find-repos

cargo run -q -p specatlas-cli -- find-analogs  --output target/specatlas-routes/find-analogs

cargo run -q -p specatlas-cli -- repo analyze  --output target/specatlas-routes/repo

cargo run -q -p specatlas-cli -- analyze  --profile safe-static --output target/specatlas-routes/analyze

cargo run -q -p specatlas-cli -- analyze-url  --profile web-observe --output target/specatlas-routes/analyze-url

cargo run -q -p specatlas-cli -- web crawl  --output target/specatlas-routes/web-crawl

cargo run -q -p specatlas-cli -- api infer  --output target/specatlas-routes/api-infer

cargo run -q -p specatlas-cli -- import  --output target/specatlas-routes/import

cargo run -q -p specatlas-cli -- decompose  --output target/specatlas-routes/decompose

cargo run -q -p specatlas-cli -- cleanroom-spec  --output target/specatlas-routes/cleanroom-spec

cargo run -q -p specatlas-cli -- agent-plan  --output target/specatlas-routes/agent-plan

cargo run -q -p specatlas-cli -- instrument  --output target/specatlas-routes/instrument

cargo run -q -p specatlas-cli -- report specatlas-project

cargo run -q -p specatlas-cli -- doctor specatlas-project

```



Product Teardown is first-class at the CLI through `teardown `. The import-backed workflow accepts structured product intent, consumes verified discovery imports, writes ranked repository candidates under `artifacts/repos/product-teardown-repositories.json`, writes search and analog artifacts under `artifacts/imports/`, then feeds the existing 30-map clean-room report and handoff pipeline. Stage routes such as `find-repos`, `find-analogs`, `research external`, and `repo analyze` are wrappers around the same evidence and policy gates.



Capability truth table:



| Stage | Status | Notes |

|---|---|---|

| Structured intake | Implemented | `--product-description`, `--example-url`, `--seed-repo`, `--stage`, and `--discovery-import` are parsed by the CLI. |

| Verified discovery import | Implemented | Reuses fixture provenance or trusted worker-output authority before evidence can be reused. |

| Search, repo, and analog artifacts | Import-backed | Writes typed artifacts only when reviewed evidence is reusable. |

| Repository ranking | Implemented | Rust core scores relevance, activity, license, maintenance, and safety from sanitized metadata. |

| Live provider discovery | Controlled-adapter boundary | Worker manifests exist for `search-discovery` and `github-discovery`, but live provider execution is not claimed. |

| Clean-room maps, reports, handoff | Implemented | Existing Product Teardown decomposition, report, and agent handoff consume sanitized evidence only. |



Plugin commands:



```bash

cargo run -q -p specatlas-cli -- plugins list examples/worker-plugin-registry

cargo run -q -p specatlas-cli -- plugins install examples/worker-plugin-registry/research.json

cargo run -q -p specatlas-cli -- plugins run examples/worker-plugin-registry research fixture-product target/plugin-output

```



## Server and MCP



Server metadata and local HTTP control plane:



```bash

cargo run -q -p specatlas-cli -- server

cargo run -q -p specatlas-cli -- server status

cargo run -q -p specatlas-cli -- server start --host 127.0.0.1 --port 7417 --max-requests 1

```



Add `--enable-demo` only for local demo mutation routes. Server status reports `local_ready`, `partially_configured`, or `configured_not_verified` based on environment configuration. Hosted boundary variables are:



```bash

SPECATLAS_DATABASE_URL=postgres://specatlas:specatlas_dev_only@localhost:5432/specatlas

SPECATLAS_OBJECT_STORE=http://127.0.0.1:9000

SPECATLAS_OBJECT_BUCKET=specatlas-artifacts

```



Local infra templates live in `infra/docker-compose.yml` and `infra/server.Dockerfile`.



MCP command:



```bash

cargo run -q -p specatlas-cli -- mcp serve

```



When stdin is non-interactive, `mcp serve` reads newline-delimited JSON-RPC and returns safe resources and tool responses.



## Web workbench



The web workbench is a read-only React and TypeScript package reviewer in `apps/web`.



```bash

npm --prefix apps/web run dev

npm --prefix apps/web run build

npm --prefix apps/web run test

npm --prefix apps/web run typecheck

```



Important facts:



- Vite serves on `127.0.0.1`.

- Build output is `apps/web/dist/`.

- The bundled sample manifest is `apps/web/public/sample-package/specatlas-package-manifest.json`.

- The required package entry is `reports/report.json`.

- The loader rejects unsafe paths and redacts blocked evidence before display.



## Desktop shell



The desktop app is a Tauri 2 shell in `apps/desktop`. It wraps the web workbench and local CLI-backed package workflows.



```bash

npm --prefix apps/desktop run dev

npm --prefix apps/desktop run build

npm --prefix apps/desktop run smoke

cargo test --manifest-path apps/desktop/src-tauri/Cargo.toml

```



The bundle target is the macOS `app` bundle configured in `apps/desktop/src-tauri/tauri.conf.json`. Local studies use the `specatlas` binary or the `SPECATLAS_CLI` environment variable when set.



## Workers and plugins



Workers are subprocess adapters, not product logic owners.



- Python entry: `workers/bin/specatlas-worker-python`.

- Node entry: `workers/bin/specatlas-worker-node`.

- Adapter schemas: `schemas/adapter_job.schema.json` and `schemas/adapter_event.schema.json`.

- Manifests: `workers/manifests/*.json`.

- Runtime profiles: `safe-static`, `web-observe`, `mobile-package`, and `report-only`.

- Example plugin registry: `examples/worker-plugin-registry/`.



Worker checks:



```bash

python3 -m compileall -q workers

python3 -m unittest discover -s workers/tests

node --test workers/node/browser-worker.test.mjs

node --check workers/node/browser-worker.mjs

```



## Package validation



Generated packages use a constrained path layout. Rebuild a package manifest with:



```bash

node scripts/build-package-manifest.mjs 

```



The manifest builder rejects symlinks, hidden paths, unsupported roots, and invalid artifact object digests. Package smoke verifies web dist, desktop config, infra templates, `schemas/evidence.schema.json`, and the release readiness log.



## Generated package layout



A complete package can include:



| Path | Purpose |

|---|---|

| `project.json` | Project metadata. |

| `run.json`, `runs/*.json` | Run metadata and history. |

| `specatlas-package-manifest.json` | Safe package file list. |

| `maps/` | 30 canonical decomposition maps plus graph projections. |

| `reports/` | Markdown, JSON, HTML, risk, UX, API, clean-room, and roadmap reports. |

| `agent/` | Clean-room rules, handoff, prompts, milestones, tasks, and task DAG files. |

| `evidence/` | Sources, events, claims, and policy decision ledgers. |

| `graphs/` | Product and software graph JSON and SQLite outputs. |

| `artifacts/` | Files, screenshots, traces, HAR, imports, repos, plugin outputs, and hashed objects. |

| `projections/` | Boundary metadata such as DuckDB status. |



## Architecture



```text

CLI commands

  -> Rust core workflows and policy

  -> workers through adapter contracts

  -> generated SpecAtlas package

  -> web, desktop, MCP, and server readers

```



Core architecture rules:



- `crates/specatlas-cli` is the command surface.

- `crates/specatlas-core` routes workflows and writes packages.

- `crates/specatlas-policy`, `specatlas-cleanroom`, `specatlas-report`, `specatlas-decomposition`, and graph crates own product logic.

- `crates/specatlas-server` owns collaboration metadata and hosted boundaries, not product analysis.

- `crates/specatlas-mcp` exposes safe resources and tools.

- `schemas/` define cross-boundary JSON contracts.



## Repository layout



| Path | Purpose |

|---|---|

| `crates/` | Rust workspace crates and CLI. |

| `apps/web/` | React package workbench. |

| `apps/desktop/` | Tauri desktop shell. |

| `workers/` | Python and Node adapter runtimes. |

| `schemas/` | JSON schemas for package and adapter contracts. |

| `scripts/` | Quality, smoke, and package manifest scripts. |

| `docs/` | Architecture, mode, safety, deployment, packaging, and development docs. |

| `examples/` | Worker job examples and plugin registry fixtures. |

| `corpus/` | Safe fixtures and golden outputs. |

| `infra/` | Local server, Postgres, and object store templates. |

| `tests/e2e/` | Full workflow Rust tests. |



## Safety model



SpecAtlas separates evidence collection from agent-consumable outputs. Blocked evidence can remain in ledgers for audit, but reports, agent handoffs, MCP resources, and web previews must show only safe references or redacted markers. Clean-room policy flags include evidence requirements, no proprietary assets, and no copied copy.



## Quality gates



`npm run quality:final` runs:



1. `cargo fmt --all -- --check`

2. `cargo clippy --all-targets --all-features -- -D warnings`

3. `cargo test --all-targets --all-features`

4. `cargo llvm-cov --workspace --all-targets --all-features --fail-under-lines 97 --summary-only -j 1`

5. `cargo run -q -p specatlas-cli -- mcp serve`

6. `cargo test --manifest-path apps/desktop/src-tauri/Cargo.toml`

7. `python3 -m compileall -q workers`

8. `python3 -m unittest discover -s workers/tests`

9. `node --test workers/node/browser-worker.test.mjs`

10. `npm run check`

11. `npm --prefix apps/desktop run build`

12. `npm run desktop:smoke`

13. `npm run package:smoke`



Do not update release readiness results unless these gates are actually run.



## Documentation map



- [Architecture](docs/architecture.md)

- [Modes](docs/modes.md)

- [Adapter spec](docs/adapter-spec.md)

- [Plugin API](docs/plugin-api.md)

- [Web workbench](docs/web-workbench.md)

- [Desktop](docs/desktop.md)

- [Deployment](docs/deployment.md)

- [Development](docs/development.md)

- [Safety](docs/safety.md)

- [Mobile companion mode](docs/mobile-companion-mode.md)

- [Packaging](docs/packaging.md)

- [Release readiness](docs/release-readiness.md)

- [Worker docs](workers/README.md)



## Agent notes



Scoped agent instructions:



- [Root agent notes](AGENTS.md)

- [Rust crates notes](crates/AGENTS.md)

- [Web workbench notes](apps/web/AGENTS.md)

- [Desktop notes](apps/desktop/AGENTS.md)

- [Workers notes](workers/AGENTS.md)

- [Docs notes](docs/AGENTS.md)

- [Scripts notes](scripts/AGENTS.md)

- [Schemas notes](schemas/AGENTS.md)

- [Infra notes](infra/AGENTS.md)

- [Tests notes](tests/AGENTS.md)

- [Corpus notes](corpus/AGENTS.md)

- [Examples notes](examples/AGENTS.md)



Read the nearest `AGENTS.md` before editing within a subdirectory.