{"id":48936674,"url":"https://github.com/ido4-dev/ido4specs","last_synced_at":"2026-04-17T12:01:41.616Z","repository":{"id":351560832,"uuid":"1211429176","full_name":"ido4-dev/ido4specs","owner":"ido4-dev","description":"Technical-spec authoring companion plugin for ido4 — turn a strategic spec into a validated technical spec ready for ingestion.","archived":false,"fork":false,"pushed_at":"2026-04-15T13:59:01.000Z","size":167,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-15T15:33:39.181Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/ido4-dev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","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-15T11:39:10.000Z","updated_at":"2026-04-15T13:59:05.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ido4-dev/ido4specs","commit_stats":null,"previous_names":["ido4-dev/ido4specs"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ido4-dev/ido4specs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ido4-dev%2Fido4specs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ido4-dev%2Fido4specs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ido4-dev%2Fido4specs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ido4-dev%2Fido4specs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ido4-dev","download_url":"https://codeload.github.com/ido4-dev/ido4specs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ido4-dev%2Fido4specs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31928229,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-17T10:35:34.458Z","status":"ssl_error","status_checked_at":"2026-04-17T10:35:09.472Z","response_time":62,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: 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":[],"created_at":"2026-04-17T12:01:27.011Z","updated_at":"2026-04-17T12:01:41.608Z","avatar_url":"https://github.com/ido4-dev.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 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\u003e size: L | risk: medium\n\nCore logic for assembling a context bundle at task start.\n\n### CAS-01: Upstream Decision Fetcher\n\u003e effort: M | risk: low | type: feature | ai: full\n\u003e 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 `\u003e 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\u003c!-- BEGIN SKILL INVENTORY --\u003e\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\u003c!-- END SKILL INVENTORY --\u003e\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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fido4-dev%2Fido4specs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fido4-dev%2Fido4specs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fido4-dev%2Fido4specs/lists"}