{"id":47709071,"url":"https://github.com/ido4-dev/ido4shape","last_synced_at":"2026-04-05T20:02:01.357Z","repository":{"id":344559704,"uuid":"1181968441","full_name":"ido4-dev/ido4shape","owner":"ido4-dev","description":"A thinking partner that helps crystallize what needs to be built — Claude Code \u0026 Cowork plugin for creative specification","archived":false,"fork":false,"pushed_at":"2026-04-02T20:33:16.000Z","size":302,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T04:44:43.422Z","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":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-03-14T21:40:27.000Z","updated_at":"2026-04-02T20:33:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ido4-dev/ido4shape","commit_stats":null,"previous_names":["ido4-dev/ido4shape"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/ido4-dev/ido4shape","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ido4-dev%2Fido4shape","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ido4-dev%2Fido4shape/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ido4-dev%2Fido4shape/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ido4-dev%2Fido4shape/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ido4-dev","download_url":"https://codeload.github.com/ido4-dev/ido4shape/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ido4-dev%2Fido4shape/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31448216,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T15:22:31.103Z","status":"ssl_error","status_checked_at":"2026-04-05T15:22:00.205Z","response_time":75,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5: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-02T18:19:35.020Z","updated_at":"2026-04-05T20:02:01.353Z","avatar_url":"https://github.com/ido4-dev.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ido4shape\n\nA specification discovery plugin primarily designed for [Cowork](https://claude.com/product/cowork), Anthropic's agentic desktop application — though it also works in Claude Code.\n\nido4shape is like having a principal consultant inside Claude — it reads your docs, probes your assumptions, tracks stakeholder tensions across sessions, and produces the kind of structured strategic specification that usually takes weeks of consulting.\n\n**Building with AI coding agents?** Your agent is only as good as the spec you give it. ido4shape produces structured specs with dependencies, priorities, and success conditions — input that makes Cursor, Claude Code, or Copilot actually deliver.\n\n**Need help thinking it through?** The agent probes your assumptions, extracts what your team knows but hasn't articulated, and turns it into something you can hand to your boss, your investors, or your dev team.\n\nEither way — every specification tool assumes you already know what to build. ido4shape starts at \"tell me about your problem.\"\n\n## Installation\n\n**Cowork (Claude Desktop):**\n\n*Pending Anthropic marketplace approval. Once approved, ido4shape will be available directly in the Anthropic \u0026 Partners directory. Until then, install via personal marketplace:*\n\n1. Click **Customize** in the left sidebar\n2. Under **Personal plugins**, click the **+** button\n3. Select **Create plugin** → **Add marketplace**\n4. Enter `ido4-dev/ido4-plugins` and click **Sync**\n5. Open the Directory, go to the **Personal** tab, and click **+** on ido4shape to install\n\n**Claude Code (CLI):**\n```bash\nclaude plugin marketplace add ido4-dev/ido4-plugins\nclaude plugin install ido4shape@ido4-plugins\n```\n\n## Getting Started\n\n1. **Prepare a project folder** with any materials you have — PRDs, meeting notes, architecture docs, research. You can also start with nothing.\n2. **Start a session:**\n   - **Cowork:** Click **\"Work in a project\"** at the bottom of the chat input and select your project folder. Then type `/create-spec my-project` or pick from the \"Get to work with ido4shape\" suggestions.\n   - **Claude Code:** Navigate to your project folder, start Claude Code, then run `/ido4shape:create-spec my-project`\n3. **Have a conversation** — the agent reads your materials, asks questions, and builds understanding. Stop and resume anytime; everything is saved.\n4. **When ready**, run `/synthesize-spec` to produce the formal spec\n\n\u003e **Cowork users:** Always select a project folder via \"Work in a project\" before starting. Without a folder selected, the plugin won't work.\n\n## Example Workflows\n\n### Starting from scratch\n\nYou have an idea but no documents. You start a session and the agent guides discovery.\n\n```\nYou: /ido4shape:create-spec my-saas-product\n\nAgent: What's your role on this project? I want to make sure I'm asking the\n       right questions.\n\nYou: I'm the founder. We're building a B2B analytics dashboard.\n\nAgent: Before we go further — who's feeling the pain right now? Is this\n       \"customers are asking for it\" or \"we think the market needs it\"?\n       That changes how we think about the problem.\n\nYou: Our existing customers keep building their own dashboards in spreadsheets.\n     We have the data, they just can't access it easily.\n\nAgent: That's a strong signal — they're already solving the problem badly.\n       What I want to understand is how acute this is. Are you losing\n       customers over it, or is it more of a retention and expansion play?\n```\n\nThe agent continues probing across problem depth, solution shape, risks, and dependencies. Understanding builds across one or several sessions depending on project complexity. Everything is saved to a knowledge canvas that persists between conversations.\n\n### Starting from existing materials\n\nYou have documents — a PRD, meeting notes, architecture sketches. Drop them in your project folder before starting.\n\n```\nYou: /ido4shape:create-spec notification-system\n\nAgent: I've read the three documents in your folder. Your architecture doc\n       describes a multi-channel notification system with email, push, and\n       SMS. The meeting notes mention a 10,000 events/minute target from\n       Marcus, and Sarah flagged that users currently miss critical alerts.\n\n       Something jumped out at me: the architecture doc assumes synchronous\n       delivery, but at 10K events/minute that's going to be a bottleneck.\n       Has the team discussed async vs sync delivery?\n```\n\nThe agent doesn't start from zero — it reads everything first, then targets the gaps. Conversations go deeper faster because you're not repeating what's already written down.\n\n### Picking up where you left off\n\nSessions can be days or weeks apart. The agent reads the canvas and continues.\n\n```\nAgent: Welcome back. Last time we mapped out three capability groups and\n       identified a dependency chain through the authentication layer.\n       Since then, I've been thinking about something — the risk around\n       the third-party API integration we discussed. We left it as an\n       open question.\n\n       The architect hasn't weighed in yet on feasibility. Should we\n       bring them in, or do you want to make an assumption and flag it?\n```\n\n### Running the full pipeline\n\nWhen understanding is deep enough, the agent proposes moving to synthesis.\n\n```\nAgent: I think we have enough to produce a solid spec. Here's the picture:\n       4 capability groups, 15 capabilities, 3 cross-cutting concerns. The\n       dependency graph is clean — no cycles, critical path through the\n       data pipeline group.\n\n       I'd recommend running the independent reviewers first — the\n       dependency auditor catches things I consistently miss. Want me\n       to launch /ido4shape:review-spec?\n\nYou: Yes, go ahead.\n\n[Three parallel reviewers run: technical feasibility, scope alignment,\n dependency audit. Each produces an independent report.]\n\nAgent: Reviews are in. Two findings worth addressing: the scope reviewer\n       flagged that Group 3 has a capability that contradicts our non-goal\n       of real-time streaming, and the dependency auditor found an\n       optimization — decoupling the auth layer from the API gateway\n       would let two groups start in parallel.\n\n       Want me to adjust the canvas and then synthesize?\n\nYou: Fix those and synthesize.\n\n[Agent updates canvas, runs /ido4shape:synthesize-spec, produces the\n strategic spec artifact, then runs /ido4shape:validate-spec]\n\nAgent: Spec produced: 4 groups, 15 capabilities, valid format, no warnings.\n       The file is at notification-system-spec.md. Ready to share with\n       your team.\n```\n\n## How It Works\n\nThe agent explores six areas of understanding. These aren't stages you walk through in order — the agent follows what matters for your specific project, jumping between topics as the conversation evolves.\n\n1. **Problem Depth** — who suffers, how acutely, what workarounds exist\n2. **Solution Shape** — what capabilities need to exist, how they relate\n3. **Boundary Clarity** — constraints, non-goals, open questions\n4. **Risk Landscape** — unknowns, external dependencies, untested assumptions\n5. **Dependency Logic** — what must exist before what\n6. **Quality Bar** — what \"done\" means for each capability\n\nThe agent adapts to your communication style and energy. It connects dots across sessions and stakeholders, surfaces tensions between conflicting requirements, and knows when to push deeper vs when to step back. When you're stuck, it proposes — it doesn't just ask more questions.\n\n## What You Get\n\nNot just a spec — the thinking behind it.\n\nThe final output is a **strategic specification** — groups of capabilities with priorities, risk assessments, dependencies, and verifiable success conditions. Designed to be read by humans and consumed by AI tools alike. See a [complete example spec](references/example-strategic-notification-system.md).\n\nBut the real value is everything the agent captures along the way:\n\n- **The knowledge canvas** — your evolving understanding, updated after every insight, readable at any time. Survives sessions, context compaction, and crashes.\n- **Decisions \u0026 tensions** — every call made and why. Contradictions between stakeholders tracked until resolved. No more \"why did we decide that?\" six weeks later.\n- **Stakeholder perspectives** — who said what, what each person cares about, which perspectives are missing. Both the PM's view and the architect's survive into the spec.\n- **Independent review** — before the spec is finalized, parallel AI reviewers check technical feasibility, scope alignment, and dependency integrity.\n\nThe spec goes wherever you need it — your dev team (as a project brief), your boss or investors (as a strategy document), AI coding agents (as structured input), or spec-driven tools like [ido4 MCP](https://github.com/ido4-dev/ido4) for automated technical decomposition.\n\n\u003c!-- BEGIN SKILL INVENTORY --\u003e\n## Skills\n\n### Commands\n\n| Skill | Description |\n|-------|-------------|\n| `/ido4shape:create-spec` | Guides users through creative specification development. |\n| `/ido4shape:refine-spec` | Edits existing spec artifacts using natural language instructions. |\n| `/ido4shape:review-spec` | Launches parallel independent reviewers to assess the canvas or spec artifact before composition. |\n| `/ido4shape:stakeholder-brief` | Generates a stakeholder-specific briefing from the current canvas. |\n| `/ido4shape:synthesize-spec` | Crystallizes a knowledge canvas into a strategic spec artifact. |\n| `/ido4shape:validate-spec` | Validates a strategic spec artifact for format compliance and content quality. |\n\n### Supporting skills (auto-triggered)\n\nThese activate automatically during conversation when relevant — you don't invoke them directly.\n\n| Skill | Description |\n|-------|-------------|\n| `artifact-format` | Provides strategic spec artifact format knowledge. |\n| `creative-decomposition` | Provides conversation methodology for creative specification work. |\n| `dependency-analysis` | Provides dependency graph knowledge. |\n| `quality-guidance` | Provides strategic spec quality standards. |\n\u003c!-- END SKILL INVENTORY --\u003e\n\n## Glossary\n\n- **Canvas** — The agent's working memory during specification. Evolves throughout conversations. Human-readable markdown.\n- **Crystallization** — Moving from fuzzy conversation to structured, formal specification.\n- **Knowledge dimensions** — Six areas the agent explores: Problem Depth, Solution Shape, Boundary Clarity, Risk Landscape, Dependency Logic, Quality Bar.\n- **Groups** — Clusters of related capabilities in a spec (e.g., \"Notification Core\", \"Email Channel\").\n- **Capabilities** — Individual units of functionality within a group, each with a description and success conditions.\n- **Strategic spec** — The output: a structured document capturing WHAT to build, for whom, and why.\n- **Cross-cutting concerns** — Non-functional requirements (performance, security, accessibility) that apply across the entire project.\n- **Success conditions** — Specific, verifiable statements of what \"done\" means for each capability.\n- **NFRs** — Non-functional requirements. Performance targets, security standards, accessibility requirements — things that aren't features but constrain how features are built.\n\n## More Information\n\n- [CONTRIBUTING.md](CONTRIBUTING.md) — How to report bugs, run tests, submit changes\n- [SECURITY.md](SECURITY.md) — Data handling, hooks, privacy\n- [Developer Guide](docs/developer-guide.md) — Spec format details, workspace structure, the ido4 pipeline\n- [CHANGELOG.md](CHANGELOG.md) — Version history\n- [Vision \u0026 Strategy](docs/vision.md) — Product vision, design philosophy, competitive analysis\n- [Documentation Index](docs/README.md) — Full documentation directory\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fido4-dev%2Fido4shape","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fido4-dev%2Fido4shape","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fido4-dev%2Fido4shape/lists"}