{"id":51033954,"url":"https://github.com/synaptiai/bdsk","last_synced_at":"2026-06-22T03:30:44.139Z","repository":{"id":350108878,"uuid":"1205356100","full_name":"synaptiai/bdsk","owner":"synaptiai","description":"Behavior-Driven Specification Kit — specification-first governance for AI-assisted code generation. Claude Code plugin with 8-phase validator, lifecycle skills, and scope enforcement.","archived":false,"fork":false,"pushed_at":"2026-04-08T23:08:28.000Z","size":208,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-09T00:28:42.728Z","etag":null,"topics":["ai-code-generation","bdd","bdsk","claude-code","claude-code-plugin","governance","specification"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/synaptiai.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-04-08T22:17:34.000Z","updated_at":"2026-04-08T23:08:33.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/synaptiai/bdsk","commit_stats":null,"previous_names":["synaptiai/bdsk"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/synaptiai/bdsk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/synaptiai%2Fbdsk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/synaptiai%2Fbdsk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/synaptiai%2Fbdsk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/synaptiai%2Fbdsk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/synaptiai","download_url":"https://codeload.github.com/synaptiai/bdsk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/synaptiai%2Fbdsk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34633796,"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-22T02:00:06.391Z","response_time":106,"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":["ai-code-generation","bdd","bdsk","claude-code","claude-code-plugin","governance","specification"],"created_at":"2026-06-22T03:30:43.439Z","updated_at":"2026-06-22T03:30:44.127Z","avatar_url":"https://github.com/synaptiai.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# **Behavior-Driven Specification Kit**\n\n**Behavior-Driven Specification Kit** (BDSK) — is a specification-first governance system for AI-assisted code generation.\n\n## Overview\n\nBDSK defines a method for AI-assisted software development that uses behavior-driven specifications, explicit assumptions, concrete examples, and execution-phase governance to reduce ambiguity before code generation and to constrain how AI agents produce code.\n\nTraditional BDD improves shared understanding between humans. BDSK extends that idea for AI: specifications are not only communication artifacts — they are **execution constraints** for AI-assisted implementation. Every change traces to an approved spec, every assumption is captured as a first-class artifact, and an 8-phase validator enforces conformance.\n\nBDSK is not a runtime architecture, agent framework, or testing library. It is a governance system for the phase where humans and AI collaborate to design and generate software.\n\n## Why BDSK\n\nBDSK solves a specific class of problems in AI-assisted development:\n\n1. **AI generates plausible but incorrect implementations** — specs alone don't prevent wrong answers\n2. **AI invents APIs and dependencies** — without grounding, AI introduces undocumented behavior\n3. **Vague requirements hide assumptions** — ambiguity gets buried in prompts and chat history\n4. **Test suites arrive too late** — incorrect design choices are already embedded before testing\n5. **Uncertainties are lost** — important decisions remain implicit in conversations\n6. **No audit trail for AI execution** — teams can't inspect whether AI stayed within approved scope\n\n## Using BDSK in Your Project\n\n### Install as a Claude Code plugin\n\nInside Claude Code:\n\n```\n/plugin marketplace add synaptiai/bdsk\n/plugin install bdsk@bdsk\n```\n\n### Initialize your repository\n\nAfter installing the plugin, run the init command in your project:\n\n```\n/bdsk-init\n```\n\nThis creates the required directory structure:\n- `artifacts/` — 12 subdirectories for governance artifacts\n- `.claude/state/` — execution state tracking\n- `.claude/CLAUDE.md` — project context template\n\n### Start using BDSK\n\nUse `/run` for the full lifecycle in one command:\n\n```\n/run \u003cfeature description\u003e\n```\n\nThis chains: specify → plan → implement → evaluate → verify → validate → accept. Only two human gates (spec review, scope review) — everything else is automatic.\n\nOr use individual skills: `/specify`, `/plan-execution`, `/evaluate`, `/verify`, `/validate`, `/accept`.\n\n### Prerequisites\n\n- [Node.js](https://nodejs.org) (v18+) — runs the bundled validator\n- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI\n- Python 3 with PyYAML (optional — for scope enforcement hooks)\n\n## The Lifecycle\n\nAll changes follow a 7-phase lifecycle:\n\n```\n  Discover ──► Specify ──► Constrain ──► Execute ──► Evaluate ──► Verify ──► Accept\n                 ▲            ▲                         │           │          │\n              human         human                    auto        auto       auto\n              gate          gate                  (escalate   (escalate  (escalate\n                                                  on fail)    on fail)   on fail)\n```\n\n\n| Phase        | Action                                                     | Skill             | Output                  |\n| ------------ | ---------------------------------------------------------- | ----------------- | ----------------------- |\n| 1. Discover  | Surface behaviors, assumptions, open questions             | —                 | —                       |\n| 2. Specify   | Formalize intended behavior with concrete examples         | `/specify`        | `behavior_spec`         |\n| 3. Constrain | Define execution boundaries and allowed operations         | `/plan-execution` | `execution_plan`        |\n| 4. Execute   | Implement within approved scope (hooks enforce boundaries) | —                 | `generated_diff`        |\n| 5. Evaluate  | Check process conformance against review gates             | `/evaluate`       | `execution_eval`        |\n| 6. Verify    | Confirm implementation matches specification via tests     | `/verify`         | `verification_artifact` |\n| 7. Accept    | Approve or reject per Algorithm E                          | `/accept`         | `acceptance_decision`   |\n\n\nHumans approve the **what** (specification and scope). The system handles the **how**.\n\n## Artifact Types\n\nBDSK uses 11 artifact types, stored as YAML in `artifacts/`:\n\n\n| Kind                    | Prefix | Directory          | Purpose                                             |\n| ----------------------- | ------ | ------------------ | --------------------------------------------------- |\n| `behavior_spec`         | BS     | `behaviors/`       | Observable expected behavior with concrete examples |\n| `assumption_record`     | AR     | `assumptions/`     | Decisions or beliefs affecting implementation       |\n| `contract_artifact`     | CA     | `contracts/`       | API contracts, schemas, and boundaries              |\n| `codegen_policy`        | CP     | `policies/`        | Rules governing AI code generation                  |\n| `review_gate`           | RG     | `gates/`           | Review checkpoints code must pass                   |\n| `execution_plan`        | EP     | `execution-plans/` | Approved scope, boundaries, allowed operations      |\n| `generated_diff`        | GD     | `diffs/`           | Code changes produced during execution              |\n| `execution_eval`        | EE     | `execution-evals/` | Process conformance assessment results              |\n| `execution_log`         | EL     | `execution-logs/`  | Step-by-step execution audit trail                  |\n| `verification_artifact` | VA     | `verifications/`   | Test results proving spec conformance               |\n| `acceptance_decision`   | AD     | `acceptance/`      | Final accept/reject decision                        |\n\n\nAll artifacts follow the canonical envelope defined in the spec, with `kind`, `id`, `status`, `trace`, `approvals`, and `spec` fields.\n\n## Skills\n\nLifecycle commands available in Claude Code:\n\n\n| Command               | Description                                                                      |\n| --------------------- | -------------------------------------------------------------------------------- |\n| `/bdsk-init`          | Initialize BDSK in a repository (create `artifacts/`, state dirs, CLAUDE.md)     |\n| `/run \u003cfeature\u003e`      | Full lifecycle in one command (2 human gates, rest automatic)                    |\n| `/specify \u003cfeature\u003e`  | Generate a `behavior_spec` with concrete given/when/then examples                |\n| `/assume \u003cstatement\u003e` | Capture an assumption as a structured `assumption_record`                        |\n| `/plan-execution`     | Generate an `execution_plan` with scope boundaries from approved specs           |\n| `/approve \u003cid\u003e`       | Approve artifacts (single, batch with `--all-draft`, or cascading with `--plan`) |\n| `/evaluate`           | Assess review gates, create `execution_eval` artifacts                           |\n| `/verify`             | Run tests, create `verification_artifact` for each behavior spec                 |\n| `/validate`           | Run the full 8-phase validator (V1–V8)                                           |\n| `/accept`             | Compute acceptance eligibility per Algorithm E                                   |\n\n\n## Validator\n\nThe reference validator runs 8 phases of conformance checking:\n\n\n| Phase | Name         | Checks                                                       |\n| ----- | ------------ | ------------------------------------------------------------ |\n| V1    | Discovery    | Find all YAML artifacts, build index, detect duplicate IDs   |\n| V2    | Schema       | Validate each artifact against its JSON schema               |\n| V3    | Trace        | Validate trace structures and canonical edge vocabulary      |\n| V4    | Referential  | Check that all referenced `target_id`s exist                 |\n| V5    | Authority    | Enforce approval rules, waivers, and authority matrix        |\n| V6    | Execution    | Verify AI stayed within approved boundaries (Algorithms A–C) |\n| V7    | Verification | Check test coverage aligns with behavior specs (Algorithm D) |\n| V8    | Acceptance   | Compute acceptance decisions (Algorithm E)                   |\n\n\n### CLI Usage\n\n```bash\nbdsk-validate \u003cpath\u003e [options]\n\nOptions:\n  -f, --format \u003ctext|yaml|json\u003e   Output format (default: text)\n  -o, --output \u003cfile\u003e             Write report to file\n  -a, --artifacts-dir \u003cpath\u003e      Artifacts directory (default: artifacts/)\n  -s, --schemas-dir \u003cpath\u003e        Schemas directory (default: schemas/)\n  -p, --phase \u003cv1-v8|all\u003e         Run specific phase (default: all)\n  -e, --execution \u003cid\u003e            Filter to specific execution plan\n      --strict                    Treat warnings as errors\n      --quiet                     Suppress non-error output\n      --verbose                   Show detailed output\n      --version                   Show validator version\n```\n\n**Exit codes:** `0` conformant, `1` non-conformant, `2` error.\n\n## Project Structure\n\n```\nbdsk/                               # Plugin root (installable via Claude Code)\n├── .claude-plugin/\n│   └── plugin.json                 # Plugin manifest\n├── skills/                         # 9 lifecycle skills\n│   ├── run/                        #   Full lifecycle orchestrator\n│   │   ├── SKILL.md\n│   │   └── references/             #   Governance principles\n│   ├── specify/SKILL.md            #   Generate behavior specs\n│   ├── assume/SKILL.md             #   Capture assumptions\n│   ├── plan-execution/SKILL.md     #   Define execution scope\n│   ├── approve/SKILL.md            #   Approve artifacts\n│   ├── evaluate/SKILL.md           #   Evaluate review gates\n│   ├── verify/SKILL.md             #   Run tests, create verification artifacts\n│   ├── validate/SKILL.md           #   Run 8-phase validator\n│   └── accept/SKILL.md             #   Compute acceptance per Algorithm E\n├── commands/\n│   └── bdsk-init.md                # Initialize BDSK in a repository\n├── hooks/                          # Scope enforcement and audit logging\n│   ├── hooks.json                  #   Hook configuration (auto-discovered)\n│   ├── run-hook.cmd                #   Cross-platform polyglot wrapper\n│   ├── check-scope.sh              #   Blocks edits outside execution scope\n│   └── log-change.sh               #   Logs all file changes\n├── schemas/                        # JSON schemas for all 11 artifact types\n├── src/                            # Validator source (TypeScript)\n├── dist/                           # Pre-compiled validator (Node.js)\n├── bdsk_specification_v_0.md       # Authoritative BDSK v0.3 specification\n├── test/                           # Test fixtures and integration tests\n├── artifacts/                      # This repo's own governance artifacts\n├── LICENSE                         # MIT\n└── package.json                    # Validator dependencies (AJV, YAML)\n```\n\n## Governance Principles\n\n1. **Concrete example primacy** — prefer explicit examples over abstract descriptions\n2. **Behavior before implementation** — specs precede code; use `/specify` first\n3. **Explicit assumptions** — capture decisions as first-class artifacts via `/assume`\n4. **Grounding before generation** — no external interfaces without approved basis\n5. **Observable verification** — behavior must be verifiable through tests or checks\n6. **Boundary discipline** — AI stays within `execution_plan` scope (enforced by hooks)\n7. **Human approval at ambiguity** — uncertainty triggers escalation, not silent choices\n8. **Traceability over intuition** — every change traces to approved inputs via `trace.upstream`\n\n## Development\n\n```bash\n# Install dependencies\nbun install\n\n# Build validator (compiles src/ → dist/)\nbun run build\n\n# Watch mode\nbun run dev\n\n# Run tests\nbun test\n\n# Type check\nbun run lint\n\n# Run hook tests\nbash test/test-hooks.sh\n\n# Run validator directly\nnode dist/cli.js . --format text --verbose --schemas-dir schemas\n```\n\n## Status\n\nBDSK specification v0.3 (draft). Validator v0.1.0.\n\nSee [`bdsk_specification_v_0.md`](bdsk_specification_v_0.md) for the full specification.\n\n## License\n\nMIT","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsynaptiai%2Fbdsk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsynaptiai%2Fbdsk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsynaptiai%2Fbdsk/lists"}