{
  "markdown": "# ido4specs\n\n**The bridge between a strategic spec and GitHub issues.**\n\n`ido4specs` is a Claude Code plugin that takes a strategic spec — yours or one produced by [ido4shape](https://github.com/ido4-dev/ido4shape) — analyzes your codebase, and produces a structurally-validated technical spec: code-grounded task decomposition with effort, risk, type, and dependency metadata. Methodology-neutral. Any downstream tool — or `/ido4dev:ingest-spec` — can turn the file into GitHub issues.\n\n**Built for** tech leads, staff engineers, and founder-engineers who plan implementation work from high-level specs and want to skip the manual decomposition tax.\n\nPart of the [ido4 ecosystem](https://github.com/ido4-dev/ido4).\n\n## What you get\n\nA technical spec like this — every task grounded in your actual code, every metadata field calibrated against codebase reality, every dependency edge traced through the parser:\n\n```markdown\n## Capability: Context Assembly\n> size: L | risk: medium\n\nCore logic for assembling a context bundle at task start.\n\n### CAS-01: Upstream Decision Fetcher\n> effort: M | risk: low | type: feature | ai: full\n> depends_on: -\n\nFetch decisions from parent issues and upstream capabilities relative to the\ncurrent task. Pulls from GitHub issue bodies and comments, filters for\nstructured decision markers.\n\n**Success conditions:**\n- Returns all decisions from the dependency chain above the task\n- Handles missing upstream gracefully (returns empty array, not error)\n```\n\n`effort` says how big it is. `risk` says how easily it goes wrong. `type` separates feature work from infrastructure. `ai` says whether to hand it to a coding agent (`full`), pair on it (`pair`), or do it yourself (`human`). `depends_on` builds the dependency graph the parser uses to compute critical path. **Every field has a semantic the bundled validator enforces.**\n\nSee [`references/example-technical-spec.md`](references/example-technical-spec.md) for a complete parseable example.\n\n## Pipeline\n\n```\nstrategic spec (ido4shape or hand-written)\n       ↓\n/ido4specs:create-spec       → technical canvas (code analysis + strategic context)\n       ↓\n/ido4specs:synthesize-spec   → technical spec (methodology-neutral)\n       ↓\n/ido4specs:review-spec       → qualitative review (Sonnet-driven, structured report)\n/ido4specs:validate-spec     → structural validation (bundled parser, deterministic)\n       ↓\n(handoff to /ido4dev:ingest-spec or any downstream tool)\n       ↓\nGitHub issues\n```\n\n`/ido4specs:refine-spec` handles iterative edits to an existing technical spec, with structural re-validation after every edit pass.\n\n## Quick start\n\nPlace your strategic spec in your project's `specs/` directory (any path works):\n\n```\nproject/\n└── specs/\n    └── notification-system-strategic-spec.md\n```\n\nThen run the pipeline:\n\n```\n/ido4specs:create-spec specs/notification-system-strategic-spec.md\n  → writes specs/notification-system-tech-canvas.md\n\n/ido4specs:synthesize-spec specs/notification-system-tech-canvas.md\n  → writes specs/notification-system-tech-spec.md\n  → auto-runs structural validation\n\n/ido4specs:review-spec specs/notification-system-tech-spec.md\n  → qualitative review with structured Spec Review Report\n```\n\nFilename suffixes carry the disambiguation: `-strategic-spec.md` for the input, `-tech-canvas.md` for the intermediate, `-tech-spec.md` for the final artifact. `specs/*-tech-*.md` is a clean glob for everything `ido4specs` produced.\n\n### Don't have a strategic spec?\n\nWrite one by hand (it needs a `> format: strategic-spec | version: 1.0` marker), or try the bundled example to see the pipeline run end-to-end:\n\n```\n/ido4specs:create-spec references/example-strategic-spec.md\n```\n\n### Expected duration and compute\n\nThe pipeline uses Opus-level compute for inline synthesis. As long as the progress indicator's token count is moving, synthesis is proceeding normally.\n\n| Spec size | create-spec | synthesize-spec | Total |\n|---|---|---|---|\n| Small (5–10 capabilities) | 3–10 min | 3–10 min | ~10–20 min |\n| Large (25+ capabilities) | 10–25 min | 10–20 min | ~25–40 min |\n\n`validate-spec`, `review-spec`, and `refine-spec` are much faster (1–5 minutes each).\n\n<!-- BEGIN SKILL INVENTORY -->\n## Skills\n\n### Commands\n\n| Skill | Description |\n|-------|-------------|\n| `/ido4specs:create-spec` | Phase 1 — strategic spec + codebase → technical canvas. |\n| `/ido4specs:doctor` | Diagnostic checks for the ido4specs plugin. |\n| `/ido4specs:refine-spec` | Edits an existing technical spec artifact using natural-language instructions. |\n| `/ido4specs:review-spec` | Runs a qualitative review of a technical spec artifact — two-stage protocol (format compliance then content quality) ... |\n| `/ido4specs:synthesize-spec` | Phase 2 — technical canvas → technical spec artifact. |\n| `/ido4specs:validate-spec` | Validates a technical spec artifact for format compliance and content quality. |\n\n### Auto-triggered skills\n\nThese activate automatically during conversation when relevant — you don't invoke them directly.\n\n| Skill | Description |\n|-------|-------------|\n| `help` | Explains what ido4specs does, what skills are available, how the pipeline works, and how to get started. |\n| `spec-quality` | Specification quality standards for technical specs. |\n<!-- END SKILL INVENTORY -->\n\n## Visible signals\n\n`ido4specs` is **polite by default** — silent in projects that don't use it, informative when they do.\n\n**SessionStart context** (injected into Claude's awareness; surfaces in the first reply):\n\n- Project has artifacts → Claude opens with the right next-step suggestion (`validate-spec`, `synthesize-spec`, etc.)\n- First session in a project with no artifacts → one-time greeting (version, getting-started hint, link to the example spec). Marker file at `${CLAUDE_PLUGIN_DATA}/welcomed-{hash}` prevents repeat.\n- Subsequent sessions in irrelevant projects → silent.\n\n### Optional: enable the status line\n\n`ido4specs` ships `scripts/statusline.sh` for users who want a project-state-aware indicator at the bottom of the Claude Code UI. Not enabled by default (Claude Code's plugin `settings.json` does not yet support shipping a `statusLine` directly). To opt in, add to `~/.claude/settings.json` (replace the path with your install location — run `/ido4specs:doctor` to get the exact path):\n\n```jsonc\n{\n  \"statusLine\": {\n    \"type\": \"command\",\n    \"command\": \"/absolute/path/to/ido4specs/scripts/statusline.sh\",\n    \"padding\": 1\n  }\n}\n```\n\nOutput examples:\n\n| Project state | Status line |\n|---|---|\n| Tech spec ready | `ido4specs · spec ✓ {name}` |\n| Canvas ready, no spec | `ido4specs · synth {name}` |\n| Strategic spec only | `ido4specs · plan {name}` |\n| No artifacts | *(silent — your previous status line falls through)* |\n\n### Disable the plugin\n\nTo disable `ido4specs` entirely for a specific project (or globally), add to `.claude/settings.json` (or `~/.claude/settings.json`):\n\n```jsonc\n{\n  \"enabledPlugins\": {\n    \"ido4specs@ido4-plugins\": false\n  }\n}\n```\n\n## How it works\n\n`ido4specs` ships two zero-dependency parser bundles that do the structural validation work:\n\n- **`dist/tech-spec-validator.js`** — `@ido4/tech-spec-format`, ~15 KB. Validates technical specs at synthesis time and on every refine-spec edit.\n- **`dist/spec-validator.js`** — `@ido4/spec-format`, ~9 KB. Parses upstream strategic specs at the start of `create-spec`.\n\nBoth are committed to git, version-marked, checksummed, and copied to `${CLAUDE_PLUGIN_DATA}` by the `SessionStart` hook so skills can invoke them deterministically. **No npm install at session start. No MCP server runtime dependency.** The parsers are the architectural seam between the AI synthesis layer and the downstream tooling — they make the technical spec a structurally validated artifact, not just a Markdown file.\n\nThis **parser-as-seam** pattern is what lets the technical spec be methodology-neutral: any downstream tool that can read the format can consume it. Today that includes `/ido4dev:ingest-spec` (which turns it into GitHub issues) and your own tooling. Tomorrow it can include anything else built against the [`@ido4/tech-spec-format`](https://github.com/ido4-dev/ido4) reference.\n\n## Resources\n\n**For users:**\n\n- [`references/example-strategic-spec.md`](references/example-strategic-spec.md) — minimal parseable strategic-spec example (try it: `/ido4specs:create-spec references/example-strategic-spec.md`)\n- [`references/example-technical-spec.md`](references/example-technical-spec.md) — minimal parseable technical-spec example\n- [`references/technical-spec-format.md`](references/technical-spec-format.md) — canonical format reference\n- [`SECURITY.md`](SECURITY.md) — what the plugin reads, what it writes, where data lives, hook surface\n- [`PRIVACY.md`](PRIVACY.md) — privacy policy: no telemetry, no analytics, no network calls, no data collection\n\n**For contributors:**\n\n- [`CONTRIBUTING.md`](CONTRIBUTING.md) — how to modify skills, run tests, release\n- [`CLAUDE.md`](CLAUDE.md) — development context for working in this repo\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",
  "bytes": 9072,
  "sha": "68cc9c214d3dc2a94bf3dfb1e290936ee1d389694280ba2d7cfed6bda0a9ca28",
  "repo_slug": "ido4-dev/ido4specs",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_ido4_dev_ido4specs_ido4specs_6b1560a0/readme"
}