{"id":44737277,"url":"https://github.com/rootspec/rootspec","last_synced_at":"2026-04-25T19:01:21.990Z","repository":{"id":325892352,"uuid":"1091975220","full_name":"rootspec/rootspec","owner":"rootspec","description":"RootSpec | Generate software bound by intent","archived":false,"fork":false,"pushed_at":"2026-04-25T03:45:05.000Z","size":13525,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-25T05:29:35.162Z","etag":null,"topics":["ai","architecture","framework","product","spec","specification","tdd","test-driven-development"],"latest_commit_sha":null,"homepage":"https://rootspec.dev","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/rootspec.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":"docs/ROADMAP.md","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-11-07T19:54:16.000Z","updated_at":"2026-04-25T03:45:09.000Z","dependencies_parsed_at":null,"dependency_job_id":"12bf318c-8dc6-4b94-ae38-a176e48a4684","html_url":"https://github.com/rootspec/rootspec","commit_stats":null,"previous_names":["rootspec/rootspec"],"tags_count":68,"template":false,"template_full_name":null,"purl":"pkg:github/rootspec/rootspec","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rootspec%2Frootspec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rootspec%2Frootspec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rootspec%2Frootspec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rootspec%2Frootspec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rootspec","download_url":"https://codeload.github.com/rootspec/rootspec/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rootspec%2Frootspec/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32273223,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-25T18:29:39.964Z","status":"ssl_error","status_checked_at":"2026-04-25T18:29:32.149Z","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":["ai","architecture","framework","product","spec","specification","tdd","test-driven-development"],"created_at":"2026-02-15T20:07:46.430Z","updated_at":"2026-04-25T19:01:21.979Z","avatar_url":"https://github.com/rootspec.png","language":"Shell","readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/rootspec-banner.png\" alt=\"RootSpec\" width=\"600\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eRootSpec\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eGenerate software bound by intent\u003c/strong\u003e\u003cbr\u003e\n  Philosophy guides implementation, never vice versa.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"CHANGELOG.md\"\u003eChangelog\u003c/a\u003e •\n  \u003ca href=\"docs/WORKFLOWS.md\"\u003eWorkflows\u003c/a\u003e •\n  \u003ca href=\"rootspec/00.FRAMEWORK.md\"\u003eFramework\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square\" alt=\"License: MIT\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/rootspec/rootspec\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/rootspec/rootspec?style=flat-square\" alt=\"GitHub stars\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## What and Why\n\nRootSpec generates software bound by intent. You declare what your product is and why it exists; everything downstream — strategies, interactions, architecture, tests — is derived in a strict hierarchy where each level can only reference the levels above. Nothing ships unless it traces back to a stated purpose.\n\nWhen code and specs can be generated trivially, the real value is **validation and proof**. The spec transforms output from \"unverifiable claims\" into \"proven implementations.\"\n\nHumans supply intent (why it exists, what users should feel). AI generates the implementation. The hierarchy enforces the boundary — upper levels encode judgment AI lacks; lower levels move at speed humans lack.\n\nRootSpec is a specification language, file structure, YAML DSL, AI-agent skills, and an orchestrator that operationalize this.\n\nSee [AXIOMS.md](rootspec/00.AXIOMS.md) for the foundational beliefs this framework is built on.\n\n**Good for:** Complex products, long-lived systems, team collaboration, AI-assisted development.\n**Not ideal for:** Throwaway prototypes, single-developer experiments.\n\n---\n\n## Quick Start\n\nInstall ([detailed instructions](https://github.com/vercel-labs/skills)):\n\n```\nnpx skills add rootspec/rootspec\n```\n\nThen:\n\n```\n/rs-init\n/rs-spec my productivity app for remote teams\n/rs-impl\n/rs-validate\n```\n\n---\n\n## Usage\n\n### Skills\n\nEach skill is an agentic loop with an iteration cap. All accept an optional **focus** argument to narrow what they work on.\n\n| Skill | Description | Mode |\n|-------|-------------|------|\n| `/rs-init [focus]` | Initialize project — directories, base files, prerequisites | Interactive |\n| `/rs-spec [focus]` | Create or update specification — interview + validation loop | Interactive (skippable) |\n| `/rs-impl [focus]` | Implement from spec — test-driven, autonomous | Non-interactive |\n| `/rs-validate [focus]` | Run tests and report results | Non-interactive |\n| `/rs-update [focus]` | Upgrade project to latest framework version | Interactive |\n| `/rs-review [focus]` | Advisory visual review of rendered UI from screenshots | Non-interactive |\n\n### Focus Examples\n\n| Command | What it does |\n|---------|-------------|\n| `/rs-spec` | Full spec interview, level by level |\n| `/rs-spec add dark mode` | Add a feature across all affected levels |\n| `/rs-spec reinterpret` | Rethink the spec from L1 down |\n| `/rs-impl MVP` | Implement stories tagged with MVP phase |\n| `/rs-impl US-101` | Implement one specific story |\n| `/rs-validate TASK_SYSTEM` | Test stories for one system |\n| `/rs-validate failing` | Re-run previously failing tests |\n\n### The Five Levels\n\n| Level | Purpose | Key Question |\n|-------|---------|-------------|\n| **1: Philosophy** | WHY \u0026 WHAT EXPERIENCE | \"What should users feel?\" |\n| **2: Truths** | Design strategies \u0026 commitments | \"What approach will we take?\" |\n| **3: Interactions** | HOW users and product interact | \"What's the behavioral pattern?\" |\n| **4: Systems** | Implementation architecture | \"How do we build this?\" |\n| **5: Implementation** | Validation \u0026 tuning (YAML) | \"Does it work? What values?\" |\n\nEach level can only reference higher levels, never lower. This prevents circular dependencies and keeps philosophy stable when implementation changes.\n\n---\n\n## In-Depth\n\n### How It Works\n\nIntent flows down: philosophy → truths → interactions → systems → implementation. Skills drive each transition; tests prove the result still binds to the original intent.\n\n### Project Structure\n\n```\nyour-project/\n├── .rootspec.json                   # Project config\n├── rootspec/                        # Specification directory\n│   ├── 00.AXIOMS.md                # Foundational beliefs (reference)\n│   ├── 00.FRAMEWORK.md             # Framework definition (reference)\n│   ├── 01.PHILOSOPHY.md            # L1: WHY \u0026 WHAT EXPERIENCE\n│   ├── 02.TRUTHS.md                # L2: Design strategies\n│   ├── 03.INTERACTIONS.md          # L3: Interaction patterns\n│   ├── 04.SYSTEMS/                 # L4: System specs\n│   │   ├── SYSTEMS_OVERVIEW.md\n│   │   └── [YOUR_SYSTEMS].md\n│   ├── 05.IMPLEMENTATION/          # L5: User stories + parameters\n│   │   ├── USER_STORIES/           # YAML → Cypress tests\n│   │   └── FINE_TUNING/            # Numeric parameter YAML\n│   ├── CONVENTIONS/                # Implementation conventions (created by /rs-impl)\n│   │   ├── technical.md            # Stack, code patterns, API, testing\n│   │   └── visual.md               # Component library, tokens, layout\n│   ├── spec-status.json            # Spec validation tracking\n│   └── tests-status.json           # Test pass/fail tracking\n└── ...\n```\n\n### Further Reading\n\n- [00.FRAMEWORK.md](rootspec/00.FRAMEWORK.md) — Complete framework specification (the language definition)\n- [docs/IMPLEMENTATION_WORKFLOW.md](docs/IMPLEMENTATION_WORKFLOW.md) — Detailed guide for translating YAML stories into code\n- [docs/CYPRESS_SETUP.md](docs/CYPRESS_SETUP.md) — Setting up E2E testing with Cypress\n\n---\n\n## Workflows\n\n| Scenario | Commands |\n|----------|----------|\n| **New project** | `/rs-init` → `/rs-spec` → `/rs-impl` → `/rs-validate` |\n| **Existing codebase** | `/rs-init` → `/rs-spec` (scans your code) → `/rs-impl` → `/rs-validate` |\n| **Add a feature** | `/rs-spec add push notifications` → `/rs-impl` → `/rs-validate` |\n| **Change the spec** | `/rs-spec update L2 trade-offs` → `/rs-impl failing` → `/rs-validate` |\n| **Run tests** | `/rs-validate` or `/rs-validate \u003cphase\u003e` or `/rs-validate TASK_SYSTEM` |\n\nSee [docs/WORKFLOWS.md](docs/WORKFLOWS.md) for detailed walkthroughs of each scenario.\n\n### Unattended runs (orchestrator)\n\nFor CI, scheduled rebuilds, or any hands-off pipeline, the [**RootSpec Orchestrator**](orchestrator/README.md) chains all phases (`init → spec → impl → validate → review`) into a single `rs-orchestrate` command — with budget caps, retries, quality gates, and resumable state. Same skills, just driven autonomously instead of interactively.\n\n---\n\n**Version v7.8.0** — See [CHANGELOG.md](CHANGELOG.md) for history. MIT [License](LICENSE). [Contributing](CONTRIBUTING.md).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frootspec%2Frootspec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frootspec%2Frootspec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frootspec%2Frootspec/lists"}