{"id":50339881,"url":"https://github.com/jed1978/ddd-architecture-coach","last_synced_at":"2026-05-29T16:01:10.668Z","repository":{"id":354831152,"uuid":"1225437289","full_name":"jed1978/ddd-architecture-coach","owner":"jed1978","description":"Claude Code skill for structured DDD architecture planning. Produces Context Maps, Aggregate designs, AI-ADRs, and Gherkin Key Examples — not code.","archived":false,"fork":false,"pushed_at":"2026-04-30T09:55:03.000Z","size":91,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-30T11:24:37.291Z","etag":null,"topics":["bounded-context","claude-code","claude-skills","ddd","domain-driven-design","gherkin","hexagonal-architecture","sbe","software-architecture"],"latest_commit_sha":null,"homepage":"","language":null,"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/jed1978.png","metadata":{"files":{"readme":"README.en.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-04-30T09:21:21.000Z","updated_at":"2026-04-30T09:55:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jed1978/ddd-architecture-coach","commit_stats":null,"previous_names":["jed1978/ddd-architecture-coach"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/jed1978/ddd-architecture-coach","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jed1978%2Fddd-architecture-coach","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jed1978%2Fddd-architecture-coach/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jed1978%2Fddd-architecture-coach/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jed1978%2Fddd-architecture-coach/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jed1978","download_url":"https://codeload.github.com/jed1978/ddd-architecture-coach/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jed1978%2Fddd-architecture-coach/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33659872,"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-05-29T02:00:06.066Z","response_time":107,"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":["bounded-context","claude-code","claude-skills","ddd","domain-driven-design","gherkin","hexagonal-architecture","sbe","software-architecture"],"created_at":"2026-05-29T16:01:09.770Z","updated_at":"2026-05-29T16:01:10.652Z","avatar_url":"https://github.com/jed1978.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# DDD Architecture Coach\n\n\u003e 繁體中文版：[README.md](README.md)\n\nA Claude Code skill that helps you make architecture decisions for DDD projects. The core is planning — producing design documents and decision records; bundled is a bc-developer subagent you can optionally use to land implementation from the spec.\n\n## What It Does\n\nGuides you through four phases of architecture planning:\n\n1. **Domain Discovery** — structured scenario modeling, event/command extraction, BC delineation, Touchpoint Map (surface × actor × co-presence), User Stories\n2. **Architecture Design** — Context Map, per-BC architecture decisions, cloud deployment blueprint, AI-ADRs\n3. **Implementation Spec** — Aggregate design, Key Examples (Gherkin/SBE), layered responsibilities, test specs, CI/CD\n4. **Review \u0026 Iterate** — five health checklists (DDD / AI / engineering / cloud / SBE)\n\nOutput is organized in a BC-centric file structure. Each BC independently progresses through discovery → design → spec, enabling incremental development.\n\n**Parallel team development**: per-BC commands (`/phase-2 \u003cBC\u003e`, `/phase-3 \u003cBC\u003e`) take BC name as a required argument, and artifacts are written under each BC's own `{coach_output_root}/{bc}/` path. Multiple developers can each own a different BC and run their own phases simultaneously without contending on a shared state file. `.claude/arch-state.md` is a personal cursor (added to `.gitignore` at bootstrap); team-shared knowledge lives in `.claude/arch-learnings.md` (append-only, safe to commit).\n\n## Skill Components\n\nThis skill ships two responsibility-separated components sharing one DDD discipline:\n\n| Component | Role | Location |\n|-----------|------|----------|\n| **Architecture Coach** (core) | Plans, drafts design docs and decisions | `SKILL.md` + `references/` |\n| **bc-developer subagent** | Lands the spec as code while enforcing DDD discipline | `assets/agents/bc-developer.md` (copied to `.claude/agents/` at Bootstrap) |\n\nThe hand-off contract is `{coach_output_root}/{bc}/spec.md`: the coach embeds DDD discipline into the spec in Phase 3 (Aggregate boundaries, UL, Invariants, Key Examples, cross-BC event communication…), and **bc-developer reads the spec and ensures that discipline actually lives in the code** — enforced layered architecture (Domain Layer with zero external dependencies), Aggregate-centric vertical slices, UL-driven naming, cross-BC communication only via Domain Events, tenant isolation, three-color SBE coverage, commit granularity of one Invariant per TDD cycle, and halt-and-report on spec ambiguity rather than guessing.\n\nIt is not merely a \"TDD subagent\" — TDD is its workflow, but landing DDD discipline is its responsibility.\n\nYou can skip bc-developer and hand the spec to your human team or other tools — the coach doesn't depend on a specific downstream — but skipping it means giving up this enforcement layer.\n\n### If You Don't Want bc-developer\n\nbc-developer is a passive subagent — it doesn't run unless invoked; sitting in `.claude/agents/` has no side effect. To remove it entirely: `rm .claude/agents/bc-developer.md`.\n\nWithout bc-developer, here are the artifacts you can hand to your downstream of choice:\n\n| Artifact | Purpose | Location |\n|----------|---------|----------|\n| `{coach_output_root}/{bc}/spec.md` | Canonical Phase 3 spec (Aggregates, Invariants, Key Examples, Ports…) | e.g. `docs/ddd/{bc}/spec.md` |\n| `.claude/rules/{bc}.md` | Rules card: UL + Aggregate top level + firewall + dispatch summary | `.claude/rules/{bc}.md` |\n| `CLAUDE.md` | Project tech-stack rules | repo root |\n\nThree downstream paths:\n\n1. **Hand to a human team** — read spec + rules card; DDD discipline enforced via code review\n2. **Feed to another code agent** (Cursor / Copilot / a Claude Code instance without this skill) — `spec.md` is stack-agnostic and works directly as prompt context\n3. **Use `assets/agents/bc-developer.md` as a checklist** (read its Constraints section, don't invoke) — apply the DDD discipline manually or through your own workflow\n\nTrade-off: DDD discipline becomes your responsibility. None of these paths give you automated spec-ambiguity halts or three-color SBE enforcement. Reading bc-developer.md as a checklist is a low-cost compensator.\n\n## What It Is Not\n\n- **The coach itself doesn't write code.** SKILL.md and the four-phase workflow only produce design documents and decision records. The bundled **bc-developer** subagent (or your own workflow) takes implementation responsibility, reading the Phase 3 `spec.md` and writing code while enforcing DDD discipline. The coach and bc-developer are joined by `spec.md` — separated by responsibility, unified by discipline.\n- **Not a Domain Storytelling or Event Storming workshop.** Phase 1 borrows vocabulary and formats from DS and ES, but Claude drafting artifacts is fundamentally different from a facilitated workshop with domain experts.\n- **Not a replacement for team discussion.** Key Examples produced by the coach are labeled as AI-drafted baselines. Final sign-off should involve cross-functional review.\n\n## Who It's For\n\n- Developers and architects who want structured DDD architecture planning with Claude Code\n- Solo developers or small teams building domain-driven systems who need an architecture thinking partner\n- Projects considering AI/LLM integration and needing systematic intervention design with fallback planning\n\n## Key Design Decisions\n\n**Decision priority** (when tradeoffs conflict):\n1. Domain correctness \u003e technical elegance\n2. Fallback completeness \u003e AI feature richness\n3. Verifiability \u003e extensibility\n4. Team executability \u003e architectural ideal\n\n**AI is not the default.** Every AI proposal must answer: why AI? what's the fallback? how to verify? A two-tier veto applies — one Hard condition (financial/legal harm without human-in-the-loop) rejects AI unconditionally; three Soft conditions (deterministic alternative reaches 95%+, fallback cost/latency comparable, no golden dataset) presume rejection unless explicitly overridden with documented rationale.\n\n**Touchpoint Map closes a DDD discovery gap.** DDD's classic toolkit (Domain Storytelling, Event Storming, User Stories) is single-driver-biased — it captures \"who did what\" but not \"who else is watching at the same time\". Phase 1 Step 5 enumerates every UI/channel surface (web, admin console, Telegram, SMS, agent console, audit viewer…) × primary actor × **secondary observers** × **freshness budget**, requiring at least one cross-surface co-presence scenario. Example: a User Story like \"customer chats with AI\" rarely makes \"agent console must mirror the conversation within 1 second\" naturally visible — Touchpoint Map forces such cross-surface NFRs to surface explicitly during Phase 1 for discussion, instead of letting them slip until development or testing. The original concept comes from Service Blueprint (Shostack, 1984); we keep it lightweight — touchpoint × actor only, dropping heavier elements harder to reproduce in a skill (journey / emotion / metrics swim lanes).\n\n**Specification by Example (SBE)** is built into Phase 3. Key Examples in Gherkin format serve simultaneously as spec, test case, and documentation.\n\n## File Structure\n\n```\nddd-architecture-coach/\n├── SKILL.md                              # Master instruction\n├── references/                            # Methodology docs the coach reads itself\n│   ├── phase1-domain-discovery.md         # Scenario Modeling + Event/Command Extraction\n│   ├── phase2-architecture-design.md      # Context Map + BC decisions + deployment\n│   ├── phase3-implementation-spec.md      # Aggregate design + SBE + test specs\n│   └── phase4-review-iterate.md           # Health checklists\n└── assets/                                # Bundled templates Bootstrap copies into your project\n    ├── agents/\n    │   └── bc-developer.md                # DDD discipline enforcer subagent (TDD workflow, stack-agnostic, model configurable)\n    ├── commands/\n    │   ├── arch-coach.md                  # Default entry; reads state, picks phase\n    │   ├── phase-1.md ... phase-4.md      # Force entry into a specific phase\n    │   └── arch-learn.md                  # Append a learning\n    └── templates/\n        ├── project-context-template.md    # Project description, tech stack, model choice\n        ├── arch-state-template.md         # Personal cursor (gitignored): last_touched.{bc, phase, at} (phase progress is derived from docs/ddd)\n        └── arch-learnings-template.md     # Coach maintains: learnings + open questions (append-only)\n```\n\n`references/` holds the methodology docs the coach reads internally; `assets/` holds the bundled files that Bootstrap copies into your project's `.claude/` directory on first run.\n\n## Project Output Structure\n\nThe coach produces artifacts in a BC-centric layout under `coach_output_root` (asked during the first Bootstrap; default `docs/ddd/`; can be changed to `docs/architecture/`, `docs/`, `packages/foo/docs/ddd/`, etc.):\n\n```\n{coach_output_root}/\n  system/\n    domain-stories.md          # Scenarios + event/command timeline (cross-BC)\n    context-map.md             # BC classification, relationships, deployment\n    touchpoints.md             # All UI/channel surfaces × actors × co-presence + derived integration patterns\n  {bc}/\n    discovery.md               # BC-local events, User Stories, UL, AI opportunities\n    decisions.md               # Architecture decisions, AI-ADRs\n    spec.md                    # Implementation specification (canonical contract for bc-developer)\n```\n\nAdditionally, once the spec stabilizes (v1.x), Phase 3 produces an implementation rules card at the project root:\n\n```\n.claude/\n  rules/\n    {bc}.md                    # UL + Aggregate top level + firewall + dispatch + DEFERRED (condensed from spec)\n```\n\nThe rules card is a quick-reference of the spec for bc-developer or any other downstream consumer; on conflict, `spec.md` wins.\n\n\u003e This skill only writes to the file system. Teams using Confluence / Notion / wiki must sync separately.\n\n## Installation\n\nThis skill follows the [Agent Skills open specification](https://agentskills.io/specification) and works with Claude Code, OpenAI Codex CLI, and any compatible client.\n\n### Claude Code\n\nPick a scope:\n\n**User-level (available in every project)**:\n```bash\nmkdir -p ~/.claude/skills\ncd ~/.claude/skills\ngit clone https://github.com/jed1978/ddd-architecture-coach.git\n```\n\n**Project-level (only active in that project)**:\n```bash\nmkdir -p .claude/skills\ncd .claude/skills\ngit clone https://github.com/jed1978/ddd-architecture-coach.git\n```\n\nClaude Code loads the skill on its next start.\n\n### OpenAI Codex CLI\n\n```bash\nmkdir -p ~/.codex/skills\ncd ~/.codex/skills\ngit clone https://github.com/jed1978/ddd-architecture-coach.git\n```\n\n### Other compatible clients\n\nThe skill folder must be named `ddd-architecture-coach` (matching the `name` field in SKILL.md). Place the folder in your client's skills directory (consult the client's documentation for the path).\n\n### Verify\n\nOpen a new conversation and run `/arch-coach`, or simply describe your project to Claude. The skill activates and runs its Bootstrap flow (four short questions).\n\n### Upgrade\n\n```bash\ncd \u003cinstall-path\u003e/ddd-architecture-coach\ngit pull\n```\n\n## Getting Started\n\n1. Install the skill in your Claude Code project (see Installation above)\n2. Run `/arch-coach` (or just describe your project to Claude)\n3. **Bootstrap is conversational**: Claude asks four short questions (one-line product description, main tech stack, team size, output root `coach_output_root`), then drafts `.claude/project-context.md` for you to review — no blank YAML to fill\n4. Bootstrap also copies `arch-state.md`, `arch-learnings.md`, the bc-developer agent, and the slash command files into `.claude/`\n5. Claude asks which model the **bc-developer subagent** (the spec-to-code enforcement layer; see \"Skill Components\" above) should use (default Sonnet 4.6; Haiku 4.5 for fast routine TDD; Opus 4.7 for deep reasoning)\n6. Phase 1 starts: you describe behaviors, Claude produces the initial domain model — you review and challenge, never fill from scratch\n\n## Requirements\n\n- Claude Code\n- A product/project description (3-5 sentences minimum)\n- Willingness to challenge Claude's architectural decisions\n\n## Origin\n\nBuilt and validated on a real multi-tenant SaaS project (AI-assisted booking + scheduling). The skill's rules, self-checks, and review findings emerged from iterative development across multiple Bounded Contexts and 1000+ tests.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjed1978%2Fddd-architecture-coach","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjed1978%2Fddd-architecture-coach","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjed1978%2Fddd-architecture-coach/lists"}