{"id":51245720,"url":"https://github.com/loiane/specs-driven-development-spring-angular","last_synced_at":"2026-06-29T04:02:38.796Z","repository":{"id":352246413,"uuid":"1214421505","full_name":"loiane/specs-driven-development-spring-angular","owner":"loiane","description":"Spec-Driven Development toolkit for Spring Boot 4 — tri-platform workflow (Claude Code · GitHub Copilot · Windsurf) for specifying, implementing, and validating Spring + Angular projects","archived":false,"fork":false,"pushed_at":"2026-06-27T23:28:34.000Z","size":394,"stargazers_count":39,"open_issues_count":0,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-28T01:13:29.408Z","etag":null,"topics":["angular","github-copilot","java","spec-driven-development","spring-boot","tdd"],"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/loiane.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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-18T14:56:23.000Z","updated_at":"2026-06-27T23:28:38.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/loiane/specs-driven-development-spring-angular","commit_stats":null,"previous_names":["loiane/specs-driven-development","loiane/specs-driven-development-spring-angular"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/loiane/specs-driven-development-spring-angular","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loiane%2Fspecs-driven-development-spring-angular","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loiane%2Fspecs-driven-development-spring-angular/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loiane%2Fspecs-driven-development-spring-angular/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loiane%2Fspecs-driven-development-spring-angular/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/loiane","download_url":"https://codeload.github.com/loiane/specs-driven-development-spring-angular/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loiane%2Fspecs-driven-development-spring-angular/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34912252,"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-06-29T02:00:05.398Z","response_time":58,"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":["angular","github-copilot","java","spec-driven-development","spring-boot","tdd"],"created_at":"2026-06-29T04:02:38.136Z","updated_at":"2026-06-29T04:02:38.788Z","avatar_url":"https://github.com/loiane.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Spec-Driven Development for Spring Boot 4 + Angular\n\nA tri-platform toolkit (Claude Code · GitHub Copilot · Windsurf) that drives **Spring Framework 7 / Spring Boot 4** and **Angular** full-stack development through a documented, self-validating workflow:\n\n\u003e **specify → review → plan → implement (TDD) → test → validate → review → commit**\n\nThe agent validates its own work via a layered harness (build, static analysis, architecture, tests, coverage, mutation, contract, security) instead of relying on a human to inspect every line.\n\n```mermaid\nflowchart LR\n    A[\"/spec\"] --\u003e B[\"/spec-review\"]\n    B --\u003e C[\"/plan\"]\n    C --\u003e D[\"/build T-NNN\"]\n    D --\u003e E[\"/test\"]\n    E --\u003e F[\"/validate\"]\n    F --\u003e G[\"/review\"]\n    G --\u003e H[\"git commit\"]\n    H --\u003e I[\"/ship\"]\n```\n\n## Why\n\n- **No invention.** During specify/review/plan/tasks, the agent never guesses; every uncertainty becomes a tracked open question that you answer before progress continues.\n- **TDD by construction.** Production code can only be written *after* a failing test exists. Hooks enforce it.\n- **Traceable.** Every acceptance criterion (`AC-NNN`) maps to tests, code, and the harness gates that exercised it.\n- **Self-validating.** A single `.github/scripts/harness.sh` runs locally and in CI; the agent reads its reports and writes a structured validation report.\n- **Pre-commit code review** by an agent that uses a Spring-specific rubric.\n- **Tri-platform** with a platform-neutral core; thin wrappers for each tool.\n\n## Install\n\nThis toolkit is a **set of files you drop into your repo**, not a package you `npm install` or `mvn install`. Pick the path that matches your situation.\n\n### Prerequisites\n\n- **Backend:** Java 25 + Maven 3.9+ (for the Spring harness to run).\n- **Frontend:** Node.js 22+ and Angular CLI 20+ (for the Angular harness — lint, typecheck, unit tests, build, e2e).\n- At least one supported agent surface installed:\n  - [Claude Code](https://docs.claude.com/en/docs/claude-code) (uses `.claude/`)\n  - [GitHub Copilot in VS Code](https://code.visualstudio.com/docs/copilot/overview) with chat enabled (uses `.github/`)\n  - [Windsurf](https://windsurf.com/) (uses `.windsurf/`)\n- `bash`, `git`, `jq` on your `PATH` (the harness scripts use them).\n\nYou only need the directories for the agent(s) you actually use; the others can be deleted. For backend-only projects, Angular tooling is not required (and vice versa).\n\n### Option A — Start a new project from this toolkit\n\n```bash\n# 1. Clone (or use as a template)\ngit clone https://github.com/loiane/specs-driven-development-spring-angular.git my-service\ncd my-service\nrm -rf .git \u0026\u0026 git init\n\n# 2. Drop in your own Spring Boot 4 application code under src/\n#    Merge .github/maven/parent-pom-fragment.xml into your pom.xml\n#    (it pins the 10-layer harness: Surefire, Failsafe, JaCoCo, PIT, Checkstyle,\n#    SpotBugs, ArchUnit deps, OWASP dep-check, OpenAPI generator).\n\n# 3. Make the scripts and hooks executable\nchmod +x .github/scripts/*.sh .claude/hooks/*.sh\n\n# 4. Verify the harness wires up\n./.github/scripts/harness.sh --report     # runs the harness and emits a JSON summary\n```\n\n### Option B — Add the toolkit to an existing Spring repo\n\n```bash\n# From the root of your existing repo:\ngit clone --depth=1 https://github.com/loiane/specs-driven-development-spring-angular.git /tmp/sdd\n\n# Copy only what you need (skip the agent dirs you won't use):\ncp -r /tmp/sdd/docs /tmp/sdd/examples .\ncp -r /tmp/sdd/.claude   .   # if you use Claude Code\ncp -r /tmp/sdd/.github   .   # if you use Copilot   (merges with existing .github/)\ncp -r /tmp/sdd/.windsurf .   # if you use Windsurf\n\nchmod +x .github/scripts/*.sh .claude/hooks/*.sh\n\n# Then merge .github/maven/parent-pom-fragment.xml into your pom.xml.\n# Then run the brownfield onboarding command from your agent (see Use below).\n```\n\n\u003e **Note on `.github/`** — if you already have `.github/workflows/`, review\n\u003e `.github/workflows/ci.yml` before copying so it doesn't clobber yours.\n\u003e The shipped `ci.yml` validates **the toolkit itself** (shellcheck, markdown\n\u003e lint, broken links, tri-platform parity). In a Spring consumer project you\n\u003e should **delete it** and add your own workflow that calls\n\u003e `./.github/scripts/harness.sh` to run the 10-layer Spring harness.\n\n### Verify per-platform wiring\n\n| Platform | Smoke test |\n| --- | --- |\n| Claude Code | Open the repo, run `/help` — you should see the command catalog. |\n| Copilot | Open Copilot Chat, type `/spec` — you should see the chat-mode prompt from `.github/chatmodes/`. |\n| Windsurf | Open Cascade, type `/spec` — Windsurf loads the workflow from `.windsurf/workflows/`. |\n\n## Use\n\nOnce installed, you drive everything from your agent's chat using slash commands. The same commands work on all three platforms.\n\n### Day-zero (brownfield only)\n\n```text\n/onboard\n```\n\nClassifies the repo, captures a baseline harness run, writes\n`.specs/_onboarding.md` and `docs/known-debt.md`, and adds any missing harness\nlayers as ratchets (so existing failures don't block you, but no new ones can\nland). See [examples/brownfield/README.md](examples/brownfield/README.md).\n\n### Per-feature loop\n\n```text\n/spec \"Add gift-card checkout\"      # or: /spec JIRA-123\n/spec-review                        # gate exit from Phase 1\n/epic-plan                          # for Epics: high-level design + slice roadmap\n/plan                               # design + tasks + .tdd-state.json\n/build T-001                        # red → green → refactor → simplify (one task at a time)\n/test --gap                         # close coverage / mutation gaps\n/validate                           # full 10-layer harness + traceability\n/review                             # pre-commit code review against the Spring rubric\ngit commit                          # YOU run this — the agent never commits\n/ship                               # post-commit ship plan + release notes (never deploys)\n```\n\nRepeat `/build T-NNN` for each task in `04-tasks.md`. The agent refuses to edit\n`src/main/**` unless `.specs/\u003cfeature-id\u003e/.tdd-state.json` shows a failing test\nfor the active task.\n\nFor Epic-sized initiatives, run `/epic-plan` after `/spec-review`, then run `/plan`\nto produce slice-level detailed design and tasks from the approved roadmap.\n\n### Read-only helpers\n\n- `/status` — see where each feature sits in the pipeline.\n- `/help [command]` — print the command catalog or a single command spec.\n\n### Natural-language aliases\n\nYou don't have to remember the slash names. These phrases are routed to the\nright command by [.claude/hooks/route-natural-language-aliases.sh](.claude/hooks/route-natural-language-aliases.sh)\nand the equivalent Copilot ([.github/instructions/always-on.instructions.md](.github/instructions/always-on.instructions.md))\nand Windsurf ([.windsurf/rules/always-on.md](.windsurf/rules/always-on.md)) instructions:\n\n| You type | Runs |\n| --- | --- |\n| \"spec this\" / \"turn this ticket into requirements\" | `/spec` |\n| \"review the spec\" | `/spec-review` |\n| \"plan this epic\" / \"design this epic\" / \"slice this epic\" | `/epic-plan` |\n| \"plan this\" / \"design this\" | `/plan` |\n| \"implement T-003\" / \"build T-003\" | `/build T-003` |\n| \"validate\" / \"run the harness\" | `/validate` |\n| \"review the code\" / \"pre-commit review\" | `/review` |\n| \"simplify the code\" / \"remove the cleverness\" | `/code-simplify` |\n| \"ship it\" / \"release this\" / \"prepare release\" | `/ship` |\n| \"onboard this repo\" | `/onboard` |\n\nFull list: [.github/prompts/](.github/prompts/) (Copilot), [.claude/commands/](.claude/commands/) (Claude Code), [.windsurf/workflows/](.windsurf/workflows/) (Windsurf).\n\n### Running the harness directly\n\nThe same gates the agent runs are reachable from a normal terminal:\n\n```bash\n./.github/scripts/harness.sh                 # all 10 layers\n./.github/scripts/harness.sh --report        # emit harness-summary.json\n./.github/scripts/check-new-code-coverage.sh # diff-coverage gate against main\n./.github/scripts/traceability.sh \u003cfeature-id\u003e\n```\n\n## Repository layout\n\n```text\ndocs/             methodology · harness-principles · spec-format · platform-mapping · artifact-contract\n.claude/          agents · skills · commands · hooks · templates · checklists · maven · settings.json   (Claude Code)\n.github/          chatmodes · prompts · instructions · skills · templates · checklists · maven · scripts · workflows/   (Copilot + CI)\n.windsurf/        rules · workflows · skills · templates · checklists · maven   (Windsurf)\nexamples/         greenfield (worked end-to-end specs) · brownfield (onboarding report)\n```\n\nEach platform directory currently carries its own copy of the skills,\ntemplates, checklists, and Maven parent-pom fragment. The CI workflow\n(`.github/workflows/ci.yml`) enforces that these copies stay in lockstep via\n`diff -rq` parity checks. A future `shared/` directory will become the single\nsource of truth — see [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Workflow artifacts\n\nEach feature lives under `.specs/\u003cfeature-id\u003e/`:\n\n| File | Phase | Owner |\n| --- | --- | --- |\n| `01-spec.md` | Specify | `spec-author` |\n| `02-spec-review.md` | Review specs | `spec-author` |\n| `03-epic-design.md` | Plan (Epic mode) | `spring-architect` / `angular-architect` |\n| `03a-epic-roadmap.md` | Plan (Epic mode) | `spring-architect` / `angular-architect` |\n| `03-design.md` | Plan | `spring-architect` / `angular-architect` |\n| `04-tasks.md` | Plan | `spring-architect` / `angular-architect` |\n| `05-implementation-log.md` | Implement (TDD) | `spring-implementer` + `spring-test-engineer` / `angular-implementer` + `angular-test-engineer` |\n| `06-test-plan.md` | Test | `spring-test-engineer` / `angular-test-engineer` |\n| `07-validation-report.md` | Validate | `spring-validator` / `angular-validator` |\n| `07a-traceability.md` | Validate | `spring-validator` / `angular-validator` |\n| `08-code-review.md` | Code review | `spring-code-reviewer` / `angular-code-reviewer` |\n\n### Stack routing\n\nEach command defaults to the Spring agent but **automatically delegates to the Angular counterpart** based on feature scope:\n\n- **Backend-only** → Spring agents\n- **Frontend-only** → Angular agents\n- **Full-stack** → both agents collaborate, splitting tasks by stack\n\nThe routing contract is documented in each command's `## Stack routing` section. See [.claude/commands/plan.md](.claude/commands/plan.md) for an example.\n\n## Documentation\n\n- [docs/methodology.md](docs/methodology.md) — the 7-phase workflow in detail\n- [docs/harness-principles.md](docs/harness-principles.md) — self-validation philosophy and gate layers\n- [docs/spec-format.md](docs/spec-format.md) — EARS-lite spec format with examples\n- [docs/platform-mapping.md](docs/platform-mapping.md) — how Claude/Copilot/Windsurf artifacts map\n- [docs/artifact-contract.md](docs/artifact-contract.md) — `.specs/\u003cid\u003e/` file layout and `.tdd-state.json` schema\n- [examples/greenfield/README.md](examples/greenfield/README.md) — full worked feature\n- [examples/brownfield/README.md](examples/brownfield/README.md) — onboarding-only walkthrough\n\n## Stack assumptions\n\n### Backend (Spring)\n\n- Java 25, Spring Framework 7, Spring Boot 4\n- Maven (Gradle support deferred)\n- REST APIs with OpenAPI\n- Module boundaries enforced via ArchUnit rules (no extra runtime dependency)\n- DB engine + migration tool (Flyway/Liquibase) auto-detected from `pom.xml`\n- Testcontainers integration tests are mandatory when Testcontainers is detected\n\n### Frontend (Angular)\n\n- Angular 20+ with standalone components\n- TypeScript strict mode\n- Route-level code splitting\n- Accessible components (ARIA, keyboard reachability)\n- Unit tests (Karma/Jest) + e2e tests (Cypress/Playwright)\n- Typed API clients (no untyped HTTP response handling)\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Floiane%2Fspecs-driven-development-spring-angular","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Floiane%2Fspecs-driven-development-spring-angular","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Floiane%2Fspecs-driven-development-spring-angular/lists"}