{
  "markdown": "# smdd-toolkit\n\n> Structured Markdown Driven Development — plan projects as prose markdown before writing code, then build component-by-component with atomic, parallel-safe sub-agents.\n\nSMDD is a pre-code paradigm: describe the whole product as short markdown files in a strict folder shape first. Code comes last, mirroring the docs. Parallel agents work only if each one owns a disjoint file set and reads the same spec — SMDD makes that possible.\n\n## Install\n\n```text\n/plugin marketplace add cyvnrs/smdd-toolkit\n/plugin install smdd-toolkit@cyvnrs-marketplace\n```\n\nThat adds four skills to Claude Code: `smdd`, `smdd-code`, `smdd-compile`, `smdd-check`.\n\n## The skills\n\n| Skill | What it does |\n|---|---|\n| `smdd` | Anchor skill. Triggers on SMDD mentions, enforces the three-step collaboration flow (plan → outline → per-component → build), explains folder and file contracts. |\n| `smdd-code` | Atomic WORK task. Builds one component: reads the md + pair + deps, writes the code file + test, commits on a feature branch, returns a structured summary. Never edits files outside the target set. |\n| `smdd-compile` | Batch orchestrator. Partitions a set of targets into parallel-safe waves, spawns one `smdd-code` worker per target (Haiku for mechanical, Sonnet for coupled), verifies with `smdd-check`. |\n| `smdd-check` | Folder-level coherence audit. Reads every md and every source file in a matched folder pair, flags mismatched fields, orphan files, broken pairs, CLAUDE.md violations. Report-only. |\n\n## Quickstart — 60 seconds\n\n1. In any Claude Code session, say: **\"let's scaffold a new project in SMDD style — a recipe tracker.\"**\n2. The `smdd` skill activates, walks you through Step 1 (plan), Step 2 (outline), Step 3 (per-component deep-dive) before writing a line of code.\n3. Once the `docs/` tree is filled, say: **\"build batch 1\"** — `smdd-compile` partitions components into parallel waves and spawns sub-agents that each build one file with tests.\n4. Before merging, say: **\"run smdd-check on the schemas folder\"** — coherence audit runs over docs and code.\n\nSee [`examples/recipe-tracker/`](examples/recipe-tracker/) for a minimal filled-in SMDD project layout.\n\n## Why this exists\n\nTwo failure modes keep showing up when you hand a coding task to an LLM:\n\n1. **The model fills gaps with assumptions you wouldn't make.** Vague specs become over-engineered code with invented patterns.\n2. **Parallel sub-agents drift apart.** Five agents produce five individually-reasonable files that don't cohere — mismatched field names, duplicated utilities, endpoints that don't match their consumers.\n\nSMDD installs a single source of truth (the `docs/` tree) that every agent reads before writing. The three-step flow prevents gap-filling. The `docs/`-mirrors-`src/` convention keeps parallel agents in disjoint file sets. Coherence audits catch what slips through.\n\nRead the full paradigm writeup at [`docs/paradigm.md`](docs/paradigm.md).\n\n## Project layout after `/plugin install`\n\nA project that uses SMDD will look like this:\n\n```text\nyour-project/\n  about.md               # stable scope: what, who for, V1 cut, V2 defer\n  STATUS.md              # live state: phase, checklist, open decisions, risks\n  LOG.md                 # append-only history: one dated entry per working day\n  docs/\n    ui/\n      home.md            # first route the user hits\n      design_language.md # colors, typography, spacing\n      uber_navigation.md # top-level nav map\n      common/            # header, sidebar, auth, theme\n      pages/             # one md per page/route\n    backend/\n      apis/              # one md per API surface group\n      core/              # workflows and orchestrators\n      config/            # auth, db, llm, engines\n      schemas/           # one md per data model\n      utils/             # one md per util\n    config/              # env, deploy, secrets\n  src/                   # mirrors docs/, written last\n```\n\n## Requirements\n\n- Claude Code (CLI, IDE extension, or desktop) with plugin support enabled.\n- A `CLAUDE.md` at your project root describing your local conventions (language version, style, logging). SMDD skills read it before writing code.\n\n## Companion conventions\n\nSMDD works best alongside:\n\n- **`uv` + Python 3.12** for backends (the default target in `smdd-code`; any language works — these are just what `smdd-code` knows how to run tests for out of the box).\n- **pnpm + vitest** or **playwright** for web frontends.\n- **Pydantic** for all non-scalar data movement (no `@dataclass`, no `Field()` sugar — bare `name: type` fields). `smdd-check` audits this.\n\nNone of these are hard requirements, but `smdd-check`'s CLAUDE.md-rule pass assumes them. Override by editing your project's `CLAUDE.md`.\n\n## Roadmap\n\nShipped in v1.0.0: `smdd`, `smdd-code`, `smdd-compile`, `smdd-check`.\n\nPlanned:\n\n- `smdd-init` — bootstrap the folder tree and git repo for a new project.\n- `smdd-debug` — structured bug-to-fix flow.\n- `smdd-test` — atomic test task.\n- More example projects beyond `recipe-tracker` — a backend-only service, and a project with the full auth pair (`ui/common/auth.md` ↔ `backend/config/auth.md`).\n\n## Contributing\n\nIssues and PRs welcome at [github.com/cyvnrs/smdd-toolkit](https://github.com/cyvnrs/smdd-toolkit).\n\nWhen proposing changes to a skill's contract, include a concrete scenario that the change enables or fixes — the skills are tight by design and every addition is a tax on readers.\n\n## License\n\nMIT. See [`LICENSE`](LICENSE).\n",
  "bytes": 5498,
  "sha": "4234ecd042316115cd4234ec1d3b486964068dcc22c891dfba919229632d71b6",
  "repo_slug": "cyvnrs/smdd-toolkit",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_cyvnrs_smdd_toolkit_smdd_toolkit_7eb94623/readme"
}