From 973186c900c1439fab3a6431cf39ff6645ca01d3 Mon Sep 17 00:00:00 2001 From: c <85012225+Cynrath@users.noreply.github.com> Date: Fri, 2 Oct 2026 13:01:53 +0300 Subject: [PATCH] docs: Spec Kit bridge integration guide and ecosystem links (TASK-0095) --- CHANGELOG.md | 10 +++ README.md | 12 ++- docs/guides/spec-kit-bridge.md | 49 ++++++++++++ ...K-0095-spec-kit-bridge-integration-docs.md | 75 +++++++++++++++++++ 4 files changed, 145 insertions(+), 1 deletion(-) create mode 100644 docs/guides/spec-kit-bridge.md create mode 100644 docs/tasks/active/TASK-0095-spec-kit-bridge-integration-docs.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 8e19dad..81f7372 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,16 @@ All notable changes to ACKit (`@cynrath/agent-context-kit`) are documented in th This project follows Semantic Versioning. +## [Unreleased] + +### Added + +- Community integration docs for GitHub Spec Kit: new + `docs/guides/spec-kit-bridge.md`, README ecosystem section and docs index + link pointing at [`@cynrath/ackit-spec-kit-bridge`](https://github.com/Cynrath/ackit-spec-kit-bridge) + (bridge CLI + native Spec Kit extension + `ackit-verified-sdd` workflow). + No ACKit core behavior changed. + ## [0.5.4] - 2026-09-22 Release-recovery patch (no runtime feature behavior beyond 0.5.3; no new diff --git a/README.md b/README.md index 87f120a..ec2dc60 100644 --- a/README.md +++ b/README.md @@ -402,10 +402,20 @@ Guide: [`docs/guides/vscode.md`](docs/guides/vscode.md) |---|---| | Architecture | [`docs/architecture/overview.md`](docs/architecture/overview.md) | | Concepts | `instruction-graph` · `context-budget` · `provider-profiles` · `readiness` · [`workflows`](docs/concepts/workflows.md) · [`intent`](docs/concepts/intent.md) · [`checkpoints`](docs/concepts/checkpoints.md) · [`evidence-verification`](docs/concepts/evidence-verification.md) | -| Guides | [`getting-started`](docs/guides/getting-started.md) · [`readiness`](docs/guides/readiness.md) · [`optimize`](docs/guides/optimize.md) · [`provider-profiles`](docs/guides/provider-profiles.md) · [`instruction-graph`](docs/guides/instruction-graph.md) · [`rule-packs`](docs/guides/rule-packs.md) · [`ci`](docs/guides/ci.md) · [`watch-dashboard`](docs/guides/watch-dashboard.md) · [`diagnostics`](docs/guides/diagnostics.md) · [`sdk`](docs/guides/sdk.md) · [`vscode`](docs/guides/vscode.md) · [`monorepo`](docs/guides/monorepo.md) · [`workflow-adoption`](docs/guides/workflow-adoption.md) · [`workflow-example`](docs/guides/workflow-example.md) · [`demo-trust-flow`](docs/guides/demo-trust-flow.md) | +| Guides | [`getting-started`](docs/guides/getting-started.md) · [`readiness`](docs/guides/readiness.md) · [`optimize`](docs/guides/optimize.md) · [`provider-profiles`](docs/guides/provider-profiles.md) · [`instruction-graph`](docs/guides/instruction-graph.md) · [`rule-packs`](docs/guides/rule-packs.md) · [`ci`](docs/guides/ci.md) · [`watch-dashboard`](docs/guides/watch-dashboard.md) · [`diagnostics`](docs/guides/diagnostics.md) · [`sdk`](docs/guides/sdk.md) · [`vscode`](docs/guides/vscode.md) · [`monorepo`](docs/guides/monorepo.md) · [`workflow-adoption`](docs/guides/workflow-adoption.md) · [`workflow-example`](docs/guides/workflow-example.md) · [`demo-trust-flow`](docs/guides/demo-trust-flow.md) · [`spec-kit-bridge`](docs/guides/spec-kit-bridge.md) | | Reference | `cli` · `config` · `rules` · `readiness` · `profile` · `rule-pack` · `instruction-graph` · `diagnostics` · `sdk` · `exit-codes` · `mcp` · `schemas` · [`drift`](docs/reference/drift.md) · [`policy`](docs/reference/policy.md) · [`status`](docs/reference/cli.md#cli-reference) · [`provider-surfaces`](docs/reference/provider-surfaces.md) | | Decisions | [`docs/decisions/`](docs/decisions/) · `v0.2.0`: [`docs/v0.2.0/`](docs/v0.2.0/) · `ADR-0025..0028`: workflow/evidence/checkpoint/policy-v2 | | Tasks | [`docs/tasks/active`](docs/tasks/active) | +| Ecosystem | [Spec Kit bridge](docs/guides/spec-kit-bridge.md) — community integration ([`@cynrath/ackit-spec-kit-bridge`](https://github.com/Cynrath/ackit-spec-kit-bridge)) connecting Spec Kit intent artifacts to ACKit tasks, evidence, verification gates, and handoffs | + +--- + +### 🔗 Ecosystem + +Community integration for ACKit and GitHub Spec Kit: [Spec Kit bridge](docs/guides/spec-kit-bridge.md) +([`@cynrath/ackit-spec-kit-bridge`](https://github.com/Cynrath/ackit-spec-kit-bridge)) connects +Spec Kit's intent-driven development artifacts to ACKit's deterministic repository context, task +lifecycle, evidence, verification, and completion gates. Offline-first, no telemetry. --- diff --git a/docs/guides/spec-kit-bridge.md b/docs/guides/spec-kit-bridge.md new file mode 100644 index 0000000..eeaff99 --- /dev/null +++ b/docs/guides/spec-kit-bridge.md @@ -0,0 +1,49 @@ +# Spec Kit bridge + +[GitHub Spec Kit](https://github.com/github/spec-kit) owns intent, +specification, planning, and task decomposition. ACKit owns deterministic +execution context, task state, evidence, verification, and completion trust. +The community bridge connects the two without forking either side: + +- **Bridge:** [`@cynrath/ackit-spec-kit-bridge`](https://github.com/Cynrath/ackit-spec-kit-bridge) + (CLI `ackit-speckit`) — community integration, MIT licensed. +- **Positioning:** ACKit Spec Kit Bridge connects GitHub Spec Kit's + intent-driven development artifacts to ACKit's deterministic repository + context, task lifecycle, evidence, verification, and completion gates. +- **Runtime:** offline-first, no cloud APIs, no LLM API, no telemetry. + +## Lifecycle + +```text +spec / plan / tasks (Spec Kit) + → ACKit task + refs (ackit-speckit sync) + → implementation + → verification bundle (ackit-speckit verify) + → completion gate (ackit-speckit gate) + → checkpoint / handoff (ackit-speckit checkpoint|handoff) + → safe completion (ackit-speckit complete) +``` + +## Quickstart (PowerShell) + +```powershell +npm install -g @cynrath/ackit-spec-kit-bridge +ackit-speckit init +ackit-speckit sync +ackit-speckit status --json +ackit-speckit verify --profile standard +ackit-speckit gate +``` + +A verdict binds the exact verified state: editing the spec, plan, tasks, the +mapped ACKit task, configs, or the Git diff makes it `STALE` and fails the +gate until you re-verify. The bridge also ships a native Spec Kit extension +(`speckit.ackit.*` commands + hooks) and an `ackit-verified-sdd` workflow; +see the [bridge README](https://github.com/Cynrath/ackit-spec-kit-bridge#readme) +and its `docs/` for the full contract. + +## Which ACKit surfaces the bridge uses + +`config check`, `scan --ci`, `readiness`, `instructions`, `optimize`, +`pack`, `skills validate`, `task`, `policy check`, `diagnostics` — composed +as subprocess checks with redacted evidence, never reimplemented. diff --git a/docs/tasks/active/TASK-0095-spec-kit-bridge-integration-docs.md b/docs/tasks/active/TASK-0095-spec-kit-bridge-integration-docs.md new file mode 100644 index 0000000..2e8ace4 --- /dev/null +++ b/docs/tasks/active/TASK-0095-spec-kit-bridge-integration-docs.md @@ -0,0 +1,75 @@ +--- +id: "TASK-0095" +title: "Spec Kit bridge integration docs" +status: active +schemaVersion: 2 +dependencies: + [] +createdAt: "2026-10-02" +completedAt: null +--- + + +## Purpose + +Add docs-only integration pointers from ACKit to the community +ACKit Spec Kit Bridge (no core behavior change). + +Authorization: the top-level user instruction for the bridge v0.1.0 program +explicitly authorizes changes in this repository (docs/integration links), +including branch/commit/push/PR/merge when CI is green. No force-push, no +history rewrite, no tag/release actions under this task. + +## Scope + +- `docs/guides/spec-kit-bridge.md` (new guide) +- `README.md` (docs table row + Ecosystem section) +- `CHANGELOG.md` (`[Unreleased]` entry) +- This task file + +## Out of scope + +- ACKit core code, schemas, CLI behavior, release actions + +## Affected files + +- `docs/guides/spec-kit-bridge.md` +- `README.md` +- `CHANGELOG.md` +- `docs/tasks/active/TASK-0095-spec-kit-bridge-integration-docs.md` + +## Required tests + +- `node scripts/check-text-hygiene.mjs ` +- `node dist/cli/index.js config check` +- `node dist/cli/index.js scan --ci` (must stay exit 0) +- `git diff --check` + +## Acceptance criteria + +- [ ] Guide renders correct links (bridge repo public). +- [ ] README/docs-table changes are link-only additions. +- [ ] CHANGELOG entry under `[Unreleased]`, no version bump. +- [ ] Hygiene + config + scan gates pass. +- [ ] PR opened from feature branch; merged only with green CI. + +## Acceptance criteria + +- [ ] Implementation matches scope. +- [ ] Test plan executed with pass counts recorded. + +## Test steps + +1. + +## Risks + +- + +## Rollback plan + +Focused commit revert. + +## Completion notes + +(placeholder)