{"id":49064613,"url":"https://github.com/reslava/loom","last_synced_at":"2026-04-20T04:10:33.257Z","repository":{"id":351177818,"uuid":"1208782575","full_name":"reslava/loom","owner":"reslava","description":"AI-native workflow engine. Weave ideas into features with persistent Markdown documents and structured AI collaboration.","archived":false,"fork":false,"pushed_at":"2026-04-15T18:01:27.000Z","size":426,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-15T18:33:54.406Z","etag":null,"topics":["ai","ai-native","cli","developer-tools","document-driven","event-sourced","git-native","llm","markdown","nodejs","productivity","typescript","vscode-extension","workflow"],"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/reslava.png","metadata":{"files":{"readme":"README.md","changelog":null,"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-04-12T18:30:56.000Z","updated_at":"2026-04-15T18:01:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/reslava/loom","commit_stats":null,"previous_names":["reslava/reslava-workflow-vsix","reslava/loom"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/reslava/loom","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reslava%2Floom","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reslava%2Floom/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reslava%2Floom/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reslava%2Floom/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/reslava","download_url":"https://codeload.github.com/reslava/loom/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reslava%2Floom/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32032340,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-20T00:18:06.643Z","status":"online","status_checked_at":"2026-04-20T02:00:06.527Z","response_time":94,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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","ai-native","cli","developer-tools","document-driven","event-sourced","git-native","llm","markdown","nodejs","productivity","typescript","vscode-extension","workflow"],"created_at":"2026-04-20T04:10:30.250Z","updated_at":"2026-04-20T04:10:33.252Z","avatar_url":"https://github.com/reslava.png","language":"TypeScript","readme":"# 🧵 Loom\n\n**Weave ideas into features with AI.**\n\n**Document-driven. Event-sourced. Git-native. AI-agnostic.**\n\nStop losing context when working with AI. Loom turns your Markdown files into a structured, versionable workflow engine that weaves human intent with AI execution.\n\n\u003e 🚀 **Stable CLI — v0.1.0 is here!**  \n\u003e The core workflow engine is complete. A VS Code extension is in active development.\n\n---\n\n## Why This Exists\n\nAI-assisted development is stuck in the **Chat Era**. You prompt, the AI generates, you copy-paste, and context is lost. Features drift. Plans go stale. There's no single source of truth.\n\nLoom replaces ephemeral chat with **persistent documents** that act as both specification and conversation log:\n\n- **Clear separation** between idea, design, planning, and execution.\n- **Automatic staleness detection** when designs change.\n- **Human-in-the-loop** approval for AI‑proposed state changes.\n- **Customizable workflows** that adapt to *your* process.\n- **Zero lock‑in** — everything is Markdown, versioned with Git.\n\n---\n\n## How It Works (In 30 Seconds)\n\n1. **Documents are the Database** — Every thread lives in a folder: `*-idea.md`, `*-design.md`, `*-plan-*.md`.\n2. **Status is Derived** — No central state file. Frontmatter (`status: active`) defines the workflow.\n3. **AI Reads the Docs** — The extension injects `design.md` (or a summary) into the AI prompt.\n4. **You Approve Changes** — AI proposes an action (e.g., \"Refine Design\"). You see a diff, click **Approve**, and only then does the file change.\n\n```text\nThread: Payment System\n├── payment-system-design.md      (status: active)   ← The root of truth\n├── plans/\n│   ├── payment-system-plan-001.md (status: implementing)\n│   └── payment-system-plan-002.md (status: stale ⚠️)\n```\n\n---\n\n## Key Features (CLI v0.1.0)\n\n| Feature | Description |\n|---------|-------------|\n| 📁 **Filesystem as DB** | 100% Git-friendly. Every state change is a versioned Markdown diff. |\n| 🔄 **Reactive Staleness** | Change a design? Linked plans are marked `staled: true` automatically. |\n| 🤖 **AI Handshake Protocol** | Structured JSON proposals + diff approval. No rogue changes. |\n| ⚙️ **Declarative Custom Workflows** | Define your own document types and transitions in `.loom/workflow.yml`. |\n| 🧩 **Built-in Effects** | Automate linting, deployment, notifications with `run_command`, etc. |\n| 🖥️ **VS Code Native** | Tree view, file decorations, toolbar commands. Fits your existing workflow. |\n| 🔌 **AI Agnostic** | Works with DeepSeek, OpenAI, Anthropic, or local models (Ollama). |\n| 🧵 **Mono \u0026 Multi‑Loom** | Work locally in a single project or manage multiple looms globally. |\n| 📊 **Rich Filtering \u0026 Sorting** | `loom status --filter status=active --sort id:asc` |\n| 🔗 **Blocker Resolution** | See exactly which steps are blocked and what's next. |\n\n---\n\n## Quick Start\n\n### 1. Install\n\n```bash\nnpm install -g @reslava/loom\n```\n\n### 2. Initialize a Workspace\n\n**Mono‑loom (inside your project):**\n```bash\ncd my-project\nloom init\n```\n\n**Multi‑loom (global workspace):**\n```bash\nloom init-multi\n```\n\n### 3. Weave Your First Idea\n\n```bash\nloom weave idea \"Add Dark Mode\"\n```\n\n### 4. Check Status\n\n```bash\nloom status\nloom status --verbose\nloom status --json\n```\n\n### 5. Explore Commands\n\n```bash\nloom --help\nloom weave --help\n```\n\n---\n\n## Example Workflow\n\n```bash\n# Create an idea\nloom weave idea \"User Authentication\" --thread auth\n\n# Auto‑finalize and create a design\nloom weave design auth\n\n# Auto‑finalize design and create a plan\nloom weave plan auth\n\n# Start working on the plan\nloom start-plan auth-plan-001\n\n# Complete steps\nloom complete-step auth-plan-001 --step 1\nloom complete-step auth-plan-001 --step 2\n\n# See progress and next action\nloom status auth --verbose\n```\n\n---\n\n## Architecture\n\nLoom is built on a clean, layered architecture:\n\n```\nCLI / VS Code  →  app (use‑cases)  →  core (domain) + fs (infrastructure)\n```\n\n- **`core`**: Pure domain logic (entities, reducers, validation, filters).\n- **`app`**: Orchestration use‑cases with dependency injection.\n- **`fs`**: Infrastructure adapters (filesystem, serialization, indexing).\n- **`cli`**: Thin delivery layer (command parsing, console output).\n\nThis separation makes Loom testable, maintainable, and ready for multiple frontends.\n\n---\n\n## Documentation\n\n| Document | Purpose |\n|----------|---------|\n| [**ARCHITECTURE.md**](./docs/ARCHITECTURE.md) | Derived state, reducers, and event flow. |\n| [**WORKFLOW_YML.md**](./docs/WORKFLOW_YML.md) | Custom workflow configuration reference. |\n| [**EFFECTS.md**](./docs/EFFECTS.md) | Catalog of built-in effects. |\n| [**AI_INTEGRATION.md**](./docs/AI_INTEGRATION.md) | AI handshake protocol and native client design. |\n| [**CLI Commands Reference**](./references/cli-commands-reference.md) | Every `loom` command documented. |\n| [**VS Code Commands Reference**](./references/vscode-commands-reference.md) | All `Loom:` commands and keybindings. |\n| [**Workspace Structure Reference**](./references/workspace-directory-structure-reference.md) | Directory layout and file naming conventions. |\n\n---\n\n## Contributing\n\nContributions are welcome! Please read [CONTRIBUTING.md](./CONTRIBUTING.md) for development guidelines and [DOCUMENTATION_GUIDE.md](./docs/DOCUMENTATION_GUIDE.md) for writing conventions.\n\n- **Report bugs** via GitHub Issues.\n- **Propose features** by opening a discussion.\n- **Improve documentation** – PRs are always appreciated.\n\n---\n\n## License\n\nMIT © 2026 Rafa Eslava\n\n---\n\n**Ready to stop losing context?**  \nStar the repo, and let's weave something great together. 🧵✨\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freslava%2Floom","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Freslava%2Floom","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freslava%2Floom/lists"}