{"id":51033715,"url":"https://github.com/launchapp-dev/animus-subject-markdown","last_synced_at":"2026-06-22T03:01:50.584Z","repository":{"id":359823832,"uuid":"1242728678","full_name":"launchapp-dev/animus-subject-markdown","owner":"launchapp-dev","description":"Markdown-file subject backend plugin for Animus","archived":false,"fork":false,"pushed_at":"2026-06-11T21:53:11.000Z","size":33,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-11T23:19:17.501Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://github.com/launchapp-dev/animus-cli","language":"Rust","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/launchapp-dev.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-05-18T17:41:32.000Z","updated_at":"2026-06-11T21:53:14.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/launchapp-dev/animus-subject-markdown","commit_stats":null,"previous_names":["launchapp-dev/animus-subject-markdown"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/launchapp-dev/animus-subject-markdown","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/launchapp-dev%2Fanimus-subject-markdown","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/launchapp-dev%2Fanimus-subject-markdown/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/launchapp-dev%2Fanimus-subject-markdown/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/launchapp-dev%2Fanimus-subject-markdown/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/launchapp-dev","download_url":"https://codeload.github.com/launchapp-dev/animus-subject-markdown/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/launchapp-dev%2Fanimus-subject-markdown/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34632723,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-22T02:00:06.391Z","response_time":106,"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":[],"created_at":"2026-06-22T03:01:49.849Z","updated_at":"2026-06-22T03:01:50.570Z","avatar_url":"https://github.com/launchapp-dev.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# animus-subject-markdown\n\nMarkdown-file subject backend plugin for [Animus](https://github.com/launchapp-dev/animus-cli).\n\nOne Markdown file per task. Frontmatter holds the structured fields the\norchestrator needs; the body is freeform. Files live in your repo, version\ncontrolled with everything else, reviewable in a pull request, editable in\nany text editor.\n\n\u003e **Why?** Most task systems lock your work items inside a SaaS database that's\n\u003e hard to grep, hard to diff, and hard to back up. This backend treats tasks\n\u003e like code: tracked in git, owned by the team, portable to any editor or CI\n\u003e system. Combine with `animus-subject-sqlite` (private/dispatch-heavy) or\n\u003e `animus-subject-linear` (team-of-record) by routing different kinds to\n\u003e different backends in your workflow YAML.\n\n## Install\n\nEither install the prebuilt binary from a release tag, or build from source:\n\n```bash\ncargo install --git https://github.com/launchapp-dev/animus-subject-markdown --tag v0.1.0\n```\n\nThen register it in your project's plugin config and let the Animus daemon\npick it up.\n\n## What it does\n\n| RPC               | Behavior                                                            |\n| ----------------- | ------------------------------------------------------------------- |\n| `subject/list`    | Walks `\u003croot\u003e/\u003ckind\u003e/*.md`, parses frontmatter, filters in-memory.  |\n| `subject/get`     | Reads one `.md` file at the deterministic path for the id.          |\n| `subject/update`  | Reads -\u003e merges frontmatter patch -\u003e atomic write back.             |\n| `subject/watch`   | `notify`-based file watcher, emits `SubjectChangedEvent` on change. |\n| `subject/schema`  | `supports_create=true`, `supports_watch=true`.                      |\n| `health/check`    | Verifies the root directory exists and is writable.                 |\n\n## File format\n\nEach subject is one `.md` file under `\u003croot\u003e/\u003ckind\u003e/`. The frontmatter is a\nstrict YAML block with fields in a fixed order; the body is freeform Markdown.\n\n```markdown\n---\nid: markdown:TASK-0001\nkind: task\ntitle: Fix the login bug\nstatus: in-progress\npriority: 3\nassignee: alice@example.com\nlabels:\n- auth\n- p1\nparent_id: null\ncreated_at: 2026-05-18T12:00:00Z\nupdated_at: 2026-05-18T13:30:00Z\nnative_status: In Progress\ndispatch_label: code-review\nstatus_metadata: {}\nattachments: []\ncustom_fields:\n  cycle: 2026-Q2-cycle-1\n---\n# Fix the login bug\n\nDescription goes here. The body is freeform Markdown. Workflow phases\ncan render it, agents can read it, humans can edit it in their IDE.\n\n## Acceptance criteria\n- [ ] Reproduces in staging\n- [ ] Fix doesn't break SSO flow\n- [ ] Test added\n\n## Notes\nLinked to ENG-123 in Linear.\n```\n\n### Determinism guarantees\n\nThe backend's writer is intentionally boring so that `git diff` on a status\nchange shows a single-line change, not a reformatting flood:\n\n- Fixed top-level field order: `id`, `kind`, `title`, `status`, `priority`,\n  `assignee`, `labels`, `parent_id`, `created_at`, `updated_at`,\n  `native_status`, `dispatch_label`, `status_metadata`, `attachments`,\n  `custom_fields`.\n- `custom_fields` keys are sorted alphabetically (`BTreeMap` under the hood).\n- `\\n` line endings only — no `\\r\\n` even on Windows.\n- Single trailing newline at end of file.\n- 2-space indentation inside YAML maps (`serde_yaml` default).\n- `null` is written explicitly for `Option`-valued top-level fields that have\n  no value, so adding a value later shows up as a one-line `git diff` rather\n  than as a key appearing out of nowhere.\n\n## IDs\n\nFormat: `markdown:\u003cKIND\u003e-\u003cSEQ\u003e` where `\u003cSEQ\u003e` is a 4-digit zero-padded\ninteger. Examples: `markdown:TASK-0001`, `markdown:ISSUE-0042`.\n\nSequence allocation:\n\n- Scans `\u003croot\u003e/\u003ckind\u003e/` for existing `\u003cKIND\u003e-NNNN.md` files at startup and\n  resumes from `max + 1`.\n- **Gaps are not filled.** If `TASK-0001` and `TASK-0003` exist, the next\n  allocation is `TASK-0004`. This keeps ids monotonic so `git blame` and\n  `git log --follow` stay readable.\n- The numeric portion can grow past 4 digits (`TASK-12345.md` is valid);\n  zero-padding is just the print format up to 9999.\n\n## Configuration (env vars)\n\n| Variable                    | Default                          | Description                                  |\n| --------------------------- | -------------------------------- | -------------------------------------------- |\n| `ANIMUS_MARKDOWN_ROOT`      | `\u003ccwd\u003e/.animus/subjects`         | Root directory for subject markdown files.   |\n| `ANIMUS_MARKDOWN_KINDS`     | `task`                           | Comma-separated subject kinds to read/write. |\n| `ANIMUS_MARKDOWN_ID_PREFIX` | `markdown:`                      | Id prefix (use e.g. `tasks:` for nicer ids). |\n\n## Project layout\n\n```\nanimus-subject-markdown/\n├── Cargo.toml\n├── plugin.toml          # plugin manifest discovered by the host\n├── src/\n│   ├── main.rs          # subject_backend_main entrypoint\n│   ├── lib.rs\n│   ├── backend.rs       # MarkdownBackend impl SubjectBackend\n│   ├── parser.rs        # YAML frontmatter + Markdown body splitter\n│   ├── writer.rs        # atomic + deterministic file writer\n│   ├── watcher.rs       # notify-based file watch\n│   ├── id_gen.rs        # sequential id allocator\n│   └── config.rs\n└── tests/\n    ├── contract.rs\n    └── fixtures/\n```\n\n## Development\n\n```bash\ncargo build --release\ncargo test\ncargo clippy --all-targets -- -D warnings\ncargo fmt --check\n./target/release/animus-subject-markdown --manifest\n```\n\n## License\n\nMIT. See [LICENSE](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flaunchapp-dev%2Fanimus-subject-markdown","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flaunchapp-dev%2Fanimus-subject-markdown","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flaunchapp-dev%2Fanimus-subject-markdown/lists"}