From ff8fdf7a1089d81183c237e1504a199ad56a7d5c Mon Sep 17 00:00:00 2001 From: Andrew Anderson Date: Thu, 24 Sep 2026 17:40:31 -0400 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=96=20docs:=20call=20Spektacular=20"Sp?= =?UTF-8?q?ek"=20and=20its=20outputs=20"speks"?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Andrew Anderson --- README.md | 2 +- .../content/community/what-is-hive-commons.md | 6 +- docs/content/hive/spektacular-runs.md | 40 +++--- docs/content/spektacular/getting-started.md | 90 ++++++------ docs/content/spektacular/readme.md | 60 ++++---- docs/content/spektacular/unknown-criteria.md | 42 +++--- public/llms.txt | 2 + scripts/sync-sibling-docs.ts | 136 +++++++++++++++++- src/app/docs/[...slug]/page.tsx | 4 +- src/app/docs/layout.tsx | 21 ++- 10 files changed, 281 insertions(+), 122 deletions(-) diff --git a/README.md b/README.md index fe45e6e..2074e21 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ Official documentation site for [Hive Commons](https://hivecommons.dev), served - **[rationguard](https://github.com/hivecommons/rationguard)** — detect and rebut rationalization patterns in AI agent output - **[promptargs](https://github.com/hivecommons/promptargs)** — template expansion for AI prompts - **[dibs](https://github.com/hivecommons/dibs)** — claim ideas so contributors get credit when agents implement them -- **[Spektacular](https://github.com/hivecommons/spektacular)** — spec-driven development for AI coding agents (canonical site: [spektacular.dev](https://spektacular.dev)) +- **[Spektacular (Spek)](https://github.com/hivecommons/spektacular)** — spec-driven development for AI coding agents (canonical site: [spektacular.dev](https://spektacular.dev)) ## How content is sourced diff --git a/docs/content/community/what-is-hive-commons.md b/docs/content/community/what-is-hive-commons.md index 886190c..07510ed 100644 --- a/docs/content/community/what-is-hive-commons.md +++ b/docs/content/community/what-is-hive-commons.md @@ -39,7 +39,7 @@ agents, and each is useful on its own. | Project | What it does | Docs | |---|---|---| | [**Hive**](https://github.com/hivecommons/hive) — flagship | A control layer for running governed fleets of AI coding agents against real repositories. | [Hive docs](/docs/hive/overview/introduction) | -| [**Spektacular**](https://github.com/hivecommons/spektacular) — newest member | Spec-driven development for AI coding agents. A markdown spec becomes a reviewed plan and an agent-driven implementation, each step a resumable state machine. | [Spektacular docs](/docs/spektacular/overview/introduction) · [spektacular.dev](https://spektacular.dev) | +| [**Spektacular (Spek)**](https://github.com/hivecommons/spektacular) — newest member | Spec-driven development for AI coding agents. A markdown spek becomes a reviewed plan and an agent-driven implementation, each step a resumable state machine. | [Spektacular docs](/docs/spektacular/overview/introduction) · [spektacular.dev](https://spektacular.dev) | | [**hotshot**](https://github.com/hivecommons/hotshot) | Screenshots that land directly in an AI coding assistant's terminal. | [hotshot docs](/docs/hotshot/overview/introduction) | | [**pluk**](https://github.com/hivecommons/pluk) | Structured event streaming for tmux sessions running AI coding agents. | [pluk docs](/docs/pluk/overview/introduction) | | [**promptargs**](https://github.com/hivecommons/promptargs) | Template expansion for prompts across Claude Code, Copilot, Goose, Bob, and others. | [promptargs docs](/docs/promptargs/overview/introduction) | @@ -48,10 +48,10 @@ agents, and each is useful on its own. ### How the pieces fit -Spektacular handles **one feature at a time**: spec → plan → implement, with +Spek handles **one feature at a time**: spec → plan → implement, with a human review between each step. Hive is where that work is **scaled up** — it orchestrates fleets of agents across repositories with the governance and -audit trail that running agents at that scale demands. A Spektacular workflow +audit trail that running agents at that scale demands. A Spek workflow is the unit of work a fleet orchestrator schedules. hotshot, pluk, promptargs, rationguard and dibs sit alongside both, making the individual agent session more observable, more reproducible, and properly attributed. diff --git a/docs/content/hive/spektacular-runs.md b/docs/content/hive/spektacular-runs.md index f4f6c61..6bd0c29 100644 --- a/docs/content/hive/spektacular-runs.md +++ b/docs/content/hive/spektacular-runs.md @@ -1,13 +1,13 @@ # Using Spektacular with Hive -Spektacular is a spec-driven development CLI: an idea becomes a **spec**, the -spec becomes a **plan**, the plan becomes **code**, and a coding agent does the +Spektacular (Spek) is a spec-driven development CLI: an idea becomes a **spek**, the +spek becomes a **plan**, the plan becomes **code**, and a coding agent does the writing at each step. Hive is the governor that decides which work gets done, who does it, and when it may land. Together they give you *long-running runs*: one GitHub issue that is too big for a single direct-fix PR moves through `spec → plan → implement` on one Hive -lease, with a human checkpoint between stages. Spektacular owns the artifacts +lease, with a human checkpoint between stages. Spek owns the artifacts (`.spektacular/specs/…`, `.spektacular/plans/…`); Hive owns the workflow (who holds the lease, when a stage is finished, when the next one is released). @@ -18,11 +18,11 @@ existing direct-fix behaviour is unchanged until you turn it on. | Stage | Who does the work | How Hive knows it is done | What releases the next stage | | --- | --- | --- | --- | -| `spec` | A contributor agent claims the `spec` stage and runs the Spektacular spec workflow in the repo | `spektacular spec status ` reports `document_status: final` | Owner checkpoint (`runs.checkpoints.spec`) | +| `spec` | A contributor agent claims the `spec` stage and runs the Spek spec workflow in the repo | `spektacular spec status ` reports `document_status: final` | Owner checkpoint (`runs.checkpoints.spec`) | | `plan` | A contributor agent claims the `plan` stage and runs the plan workflow | `spektacular plan status ` reports `final`; Hive imports the plan's tasks as a DRAFT epic | Plan approval (`POST /api/plans/{id}/approve`, `!runs approve `, or the dashboard checkpoint) | | `implement` | Contributor agents claim the imported tasks | Existing hold-gated PR flow | — | -Hive never opens a Spektacular file. Every fact about an artifact comes +Hive never opens a Spek file. Every fact about an artifact comes through the CLI (`spektacular … status`), and a test in `pkg/spektacular` enforces that. @@ -31,7 +31,7 @@ enforces that. 1. **A Hive v6 hub** running at ACMM L3 or higher (you need agents that can claim work). See [Getting Started](/docs/hive/getting-started). 2. **The `spektacular` binary reachable by the hub process.** - Spektacular is **not** baked into the Hive image. Install it where the hub + Spek is **not** baked into the Hive image. Install it where the hub runs, or mount it in: ```bash @@ -43,7 +43,7 @@ enforces that. For a containerised hub, bind-mount the binary and point `runs.spektacular.binary` at it (see below). -3. **The target repository initialised for Spektacular** with the same agent +3. **The target repository initialised for Spek** with the same agent backend your contributors use: ```bash @@ -55,11 +55,11 @@ enforces that. This installs the spec/plan/implement skills your agents will invoke and creates the `.spektacular/` project. Commit it: Hive contributors clone the repo and need the skills present. -4. **The hub's working directory must resolve the Spektacular project.** The +4. **The hub's working directory must resolve the Spek project.** The runner executes `spektacular status ` from the hub process's current directory with no `--dir` flag. Either start the hub from a checkout that carries the `.spektacular/` project, or register the repo - in a Spektacular `config.yaml` at the hub's cwd (`repos:` list). If the + in a Spek `config.yaml` at the hub's cwd (`repos:` list). If the status call answers `artifact_not_found` for a name your agent just wrote, this is the first thing to check. @@ -128,7 +128,7 @@ the lease (`triage_verdict`, `triage_rationale`) and shown in `GET /api/runs`. ## What happens next 1. A contributor agent claims `spec: ` from the queue. Its prompt - is the run-stage work item; the agent uses the installed Spektacular skill + is the run-stage work item; the agent uses the installed Spek skill to write `.spektacular/specs/.md` and mark it final. 2. Every 30 s the runner asks `spektacular spec status `. - `draft` → leave the lease alone. @@ -145,7 +145,7 @@ the lease (`triage_verdict`, `triage_rationale`) and shown in `GET /api/runs`. in the queue, one work item per plan task with the plan's dependencies preserved. 5. Implementation is the normal Hive PR flow: hold gates, review, DCO, - attribution. There is no Spektacular document for `implement`; the runner + attribution. There is no Spek document for `implement`; the runner never polls it. Watch it with: @@ -164,9 +164,9 @@ The Runs card on the dashboard and `!runs` in chat show the same data. retried once, and the second expiry raises a `decision`-severity escalation. No third generation is minted; a person resets the stage or abandons the run. -- If a `final` artifact flips back to `draft` (someone edited the spec), the +- If a `final` artifact flips back to `draft` (someone edited the spek), the runner refuses to advance and parks the lease with reason `stale_plan`. -- If Spektacular strict mode invalidates an approved plan, `plan status` +- If Spek strict mode invalidates an approved plan, `plan status` reports `stale`. Hive parks the run with `waiting_on: human`, `waiting_reason: stale_plan`. Recovery is a fresh plan and re-approval — it is never retried automatically. @@ -182,9 +182,9 @@ The Runs card on the dashboard and `!runs` in chat show the same data. | --- | --- | | Hub log: `[spektacular] stage runner installed` never appears | `runs.spektacular.enabled` is false or the hub was not restarted | | Stage leases exist but no agent claims them | `governor.work_source.run_stages` is not `true` | -| `artifact_not_found` for a name the agent wrote | Hub cwd does not resolve the Spektacular project (prerequisite 4), or the name was passed with `.md` / a path — always the bare `000057_name` | -| `unknown flag: --json` | Wrong Spektacular version; no verb takes `--json`, output is already JSON | -| Plan reaches `final` but stays parked, `import error` in log | Plan has neither `tasks.json` nor a parseable `- [T1] …` list; `plan export` is not yet in your Spektacular build | +| `artifact_not_found` for a name the agent wrote | Hub cwd does not resolve the Spek project (prerequisite 4), or the name was passed with `.md` / a path — always the bare `000057_name` | +| `unknown flag: --json` | Wrong Spek version; no verb takes `--json`, output is already JSON | +| Plan reaches `final` but stays parked, `import error` in log | Plan has neither `tasks.json` nor a parseable `- [T1] …` list; `plan export` is not yet in your Spek build | | `implement` never appears | The imported plan epic is still a DRAFT — approve it | | `runs.checkpoints.implement: false` is ignored | Hub is below ACMM L5; the implement checkpoint stays blocking | @@ -194,12 +194,12 @@ The Runs card on the dashboard and `!runs` in chat show the same data. ([spektacular#50](https://github.com/hivecommons/spektacular/issues/50)); until it ships, Hive uses the `tasks.json` / `plan.md` fallback. - The runner has no per-repo working directory; one hub serving several - Spektacular projects depends on a `config.yaml` `repos:` list at the hub's + Spek projects depends on a `config.yaml` `repos:` list at the hub's cwd. -- Spektacular is not shipped in the Hive image; installing or mounting it is +- Spek is not shipped in the Hive image; installing or mounting it is the operator's job. - The in-tree acceptance test (`just runs-e2e-v6`) exercises a **fake** - Spektacular CLI. Run a real spec/plan on a scratch repo before turning the + `spektacular` CLI. Run a real spek/plan on a scratch repo before turning the runner on for a repo you care about. ## Reference @@ -207,4 +207,4 @@ The Runs card on the dashboard and `!runs` in chat show the same data. - [Spektacular stage runner](https://github.com/hivecommons/hive/blob/v6/src/docs/spektacular.md) — the full contract, receipt shape and fake-CLI scenarios - [Runs](https://github.com/hivecommons/hive/blob/v6/src/docs/runs.md) — `/api/runs`, checkpoint policy, acceptance tests - [Work sources](https://github.com/hivecommons/hive/blob/v6/src/docs/work-sources.md) — `run_stages: true` and the `!:` key -- [Spektacular README](/docs/spektacular/readme) and [How to use Spektacular](/docs/spektacular/getting-started) — the CLI itself +- [Spektacular (Spek) README](/docs/spektacular/readme) and [How to use Spek](/docs/spektacular/getting-started) — the CLI itself diff --git a/docs/content/spektacular/getting-started.md b/docs/content/spektacular/getting-started.md index 0fcbe9f..360ca5d 100644 --- a/docs/content/spektacular/getting-started.md +++ b/docs/content/spektacular/getting-started.md @@ -4,7 +4,7 @@ # How to use Spektacular -_Take a feature from a rough idea to working code using a Spektacular spec, the project knowledge base, and a plan-and-implement loop driven by your coding agent of choice._ +_Take a feature from a rough idea to working code using a Spektacular (Spek) spek, the project knowledge base, and a plan-and-implement loop driven by your coding agent of choice._ AI coding agents are very good at producing code that looks right. The problem is that *looks right* and *is right for your codebase* are rarely the same @@ -17,7 +17,7 @@ The common response is to iterate: prompt, review, correct, prompt again. This works, but it is slow, and it tends to surface the same mistakes repeatedly. The agent does not learn what your team already knows. -In this tutorial you will see how Spektacular's Spec Driven Development workflow +In this tutorial you will see how Spek's Spec Driven Development workflow improves this iterative process by taking a measured, planned approach to feature development. @@ -26,29 +26,29 @@ datastore to an existing Go HTTP API as the example. The example itself does not matter much; what matters is the pattern, and the part of the pattern where most runs succeed or fail: providing the right context. -The tutorial works with every coding agent Spektacular supports. Pick yours at +The tutorial works with every coding agent Spek supports. Pick yours at the top of the page, and the agent-specific commands and screenshots will swap to match. ## What is Spektacular -Spektacular is a CLI and a collection of skills that integrates with your coding +Spek is a CLI and a collection of skills that integrates with your coding agent and drives Spec Driven Development end to end. It is agent-agnostic, shipping with adapters for Claude Code, Codex, and Bob, and it has a pluggable -data layer so you can store your specs and knowledge base in whatever way works +data layer so you can store your speks and knowledge base in whatever way works for you. There are three agent skills that do the real work: ```bash /spek-new # scaffold a new specification -/spek-plan # turn a spec into a detailed implementation plan +/spek-plan # turn a spek into a detailed implementation plan /spek-implement # drive the agent through the plan ``` Each skill runs as a resumable state machine. You can stop in the middle of a run, edit a file, and pick the run back up. Nothing is hidden inside opaque -agent state: the spec, the plan, the supporting research and context documents, +agent state: the spek, the plan, the supporting research and context documents, and the project knowledge base all live on disk where you can read and edit them. @@ -99,7 +99,7 @@ git checkout tutorial ### Step 2: Install Spektacular -Spektacular is a Go binary. Install it from GitHub releases, Homebrew, or your +Spek is a Go binary. Install it from GitHub releases, Homebrew, or your distribution's package manager. Pick whichever method fits your workflow from the [installation guide](https://spektacular.dev/install/). @@ -111,7 +111,7 @@ spektacular --version ### Step 3: Install and configure your coding agent -Spektacular drives an external coding agent. Install the one you picked at the +Spek drives an external coding agent. Install the one you picked at the top of the page. The rest of the tutorial assumes it is on your `PATH`. **Claude Code** @@ -134,9 +134,9 @@ bob --version **Codex** -Install the Codex CLI and complete its first-run setup. Spektacular +Install the Codex CLI and complete its first-run setup. Spek invokes `codex` non-interactively for each phase, so make sure the -CLI succeeds outside Spektacular before continuing. +CLI succeeds outside Spek before continuing. ```bash codex --version @@ -144,12 +144,12 @@ codex --version ### Step 4: Initialise your project -Every repository you want to use Spektacular with needs to be initialised. +Every repository you want to use Spek with needs to be initialised. This installs the skills into your coding agent and configures the local knowledge base for the project. -Run `spektacular init` from the root of the codebase you want Spektacular to -operate on, passing your chosen agent's identifier so Spektacular knows which +Run `spektacular init` from the root of the codebase you want Spek to +operate on, passing your chosen agent's identifier so Spek knows which CLI to drive. **Claude Code** @@ -192,7 +192,7 @@ Let's now look a little deeper at the specification. If you have worked with Product Requirement Documents (PRDs), you will be familiar with the process of translating business requirements into a technical -specification that you can turn into code. The specification in Spektacular +specification that you can turn into code. The spek in Spek serves the same purpose: it is a hint to the agent about what you want to build. @@ -201,7 +201,7 @@ build, not *how* you want to build it. The *how* is the agent's job. The Spec Driven Development process guides the agent to produce code that satisfies your requirements and fits the way your system is already built. -The specification in the Spektacular workflow is a markdown file with the +The spek in the Spek workflow is a markdown file with the following sections: * Overview * Requirements @@ -212,9 +212,9 @@ following sections: * Non-Goals The content in these sections guides the agent when it creates the technical -plan that is later implemented. Time invested in the specification pays off, +plan that is later implemented. Time invested in the spek pays off, because the resulting plan is more likely to be correct and to contain the -features you actually want. The spec also serves as living documentation, and it +features you actually want. The spek also serves as living documentation, and it lets you collaborate with your team on the requirements before any code is written. @@ -244,7 +244,7 @@ You will be prompted to enter the name of the feature that you want to build. For the tutorial we are going to use `SQLite migration` as the feature name. -Spektacular will automatically create the file name for the spec and allocate an +Spek will automatically create the file name for the spek and allocate an ID to it. This depends on the configuration for your project. The configuration for the example is stored at `.spektacular/config.yaml`; the following shows the config for the spec section. @@ -258,16 +258,16 @@ spec: ``` When you enter the name SQLite migration into the prompt box, you will be -prompted to run a command. The way Spektacular works is that the skill +prompted to run a command. The way Spek works is that the skill prompts the agent to call the Spektacular CLI with the right arguments. This -handles tasks like creating the spec file and enabling knowledge base +handles tasks like creating the spek file and enabling knowledge base lookups. ![spektacular command approval](images/tutorials/getting-started/approval-claude.png) -Once you approve, an empty spec will be created in the folder +Once you approve, an empty spek will be created in the folder `.spektacular/specs`, and the agent will then start to prompt you to complete -the sections of the spec. +the sections of the spek. ### Overview @@ -298,8 +298,8 @@ Once you submit it, the agent will move on to the next section, which is the requirements. Your agent will probably ask you for permission to write to a temporary file. -Spektacular writes all temporary content and context to disk before creating the -final specification or plan. This makes the workflow resumable, and it also lets +Spek writes all temporary content and context to disk before creating the +final spek or plan. This makes the workflow resumable, and it also lets you see and edit the working copy. ### Requirements @@ -498,25 +498,25 @@ limits the scope of the plan. ![spec non-goals](images/tutorials/getting-started/non-goals-bob.png) The skill tells the agent to suggest non-goals for you, based on the -current specification and the answers you have already provided. In this +current spek and the answers you have already provided. In this instance the non-goals are correct for our feature, so we can just use the suggested list. -That completes the final section of the specification. The next step is for the -agent to verify the specification before writing it to the specs directory. +That completes the final section of the spek. The next step is for the +agent to verify the spek before writing it to the specs directory. ### Verification [Watch this section on YouTube (from 8:22)](https://youtu.be/ZRVa9gml_Bg?t=502) -In the final step, the agent runs a pass over the specification to verify that it +In the final step, the agent runs a pass over the spek to verify that it is complete and meets the requirements for a good specification. -It does this in two ways. First, it checks that the specification is well formed. +It does this in two ways. First, it checks that the spek is well formed. Second, a subagent is launched with only the finished document (not the -working files, context, or conversation), which forces it to judge the spec the +working files, context, or conversation), which forces it to judge the spek the way a third-party reviewer would. Any feedback from the subagent is passed back -to the main agent, which can make final adjustments before writing the spec to +to the main agent, which can make final adjustments before writing the spek to disk. **Claude Code** @@ -527,9 +527,9 @@ disk. ![finished spec](images/tutorials/getting-started/finished-bob.png) -The agent will now generate your full specification and write it to the defined +The agent will now generate your full spek and write it to the defined specification store (in this case `.spektacular/specs/`). You can open the file -and review the final specification. It should look something like this: +and review the final spek. It should look something like this: ```markdown # Feature: 20260605141835-sqlite-migration @@ -547,8 +547,8 @@ Today the monster and user records are kept in plain text files. This feature mo - The system must query the datastore on demand instead of loading all monster and user data into memory at startup. ``` -When reviewing the specification, you may find elements you want to change or -add. You can either edit the spec directly, or chat with the agent and ask it to +When reviewing the spek, you may find elements you want to change or +add. You can either edit the spek directly, or chat with the agent and ask it to make the changes for you. Before we move on to the next phase of Spec Driven Development, the plan phase, @@ -579,7 +579,7 @@ As a developer, before you start coding, you assemble all of this information. It is often the difference between success and failure. So if the agent is going to act on your behalf, it needs the same context you do. -Spektacular gives you two tiers to put that context in: +Spek gives you two tiers to put that context in: * A repository's own knowledge, about that repository's code * The project's shared knowledge, for anything that spans repositories @@ -712,7 +712,7 @@ func (h *Handler) GetMonster(w http.ResponseWriter, r *http.Request) As you can see, this code uses both conventions: Context Cancellation and Dependency Injection. This follows Go best practice and idioms. Should your team have a different approach, you can of course capture that in the knowledge base, and the agent will use it instead. -Let's now look at the concept of a team knowledge base and learn how Spektacular +Let's now look at the concept of a team knowledge base and learn how Spek supports multiple knowledge sources. ### Knowledge that spans repositories @@ -748,7 +748,7 @@ knowledge: location: knowledge ``` -When the agent searches for context, Spektacular queries every store the request +When the agent searches for context, Spek queries every store the request covers and aggregates the results, tagging each one with the tier and store it came from. Narrow a request with `--tier` and `--filter` when you only want particular stores. These results are passed back to the agent, which can use @@ -764,7 +764,7 @@ The plan is the technical implementation blueprint of what the agent will produce. It provides enough detail to give you a firm idea of direction and enough context for the implementation itself. -As with the specification, you create a plan using the `spek-plan` skill. +As with the spek, you create a plan using the `spek-plan` skill. **Claude Code** @@ -774,12 +774,12 @@ As with the specification, you create a plan using the `spek-plan` skill. ![plan start](images/tutorials/getting-started/plan-bob.png) -The agent will then prompt you to enter the name of the specification you -want to generate a plan for. Select the spec you just created, and the +The agent will then prompt you to enter the name of the spek you +want to generate a plan for. Select the spek you just created, and the agent will start to generate the plan using the configured context. During the planning process, the agent will ask you for clarification on any -points it cannot infer from the specification or the context. +points it cannot infer from the spek or the context. **Claude Code** @@ -790,7 +790,7 @@ points it cannot infer from the specification or the context. ![plan questions](images/tutorials/getting-started/plan-question-bob.png) You will also be asked to confirm some architectural decisions the agent has -retrieved from the specification and the context. +retrieved from the spek and the context. **Claude Code** @@ -876,4 +876,4 @@ stay the same regardless of which tool you use: - **Process**: spec, plan, refine, implement, with humans in the loop at every transition. -In addition to producing better, more correct code, the process also produces a living record of the work that was done, and why. The specification and plan are both written down, and the implementation is reviewed and approved by a human at every step. This makes it easier to onboard new team members, to review past decisions, and to understand how the system works. +In addition to producing better, more correct code, the process also produces a living record of the work that was done, and why. The spek and plan are both written down, and the implementation is reviewed and approved by a human at every step. This makes it easier to onboard new team members, to review past decisions, and to understand how the system works. diff --git a/docs/content/spektacular/readme.md b/docs/content/spektacular/readme.md index 3c163bc..a95437c 100644 --- a/docs/content/spektacular/readme.md +++ b/docs/content/spektacular/readme.md @@ -4,53 +4,55 @@ # Spektacular -Agent-agnostic CLI tool for spec-driven development, providing skills and integrations for coding agents (Claude, Bob, Codex) to plan and implement work from a written spec. +> Spektacular — Spek for short. The specs it produces are called speks. + +Agent-agnostic CLI tool for spec-driven development, providing skills and integrations for coding agents (Claude, Bob, Codex) to plan and implement work from a written spek. > **Status:** early development — see the [releases page](https://github.com/hivecommons/spektacular/releases) for the latest version. ## What is Spektacular? -Spektacular is a self-contained Go binary that brings spec-driven development to AI coding agents. You write a markdown specification; Spektacular turns it into a reviewed implementation plan and then drives a coding agent to implement it — keeping your intent reviewable at every stage. +Spek is a self-contained Go binary that brings spec-driven development to AI coding agents. You write a markdown spek; Spek turns it into a reviewed implementation plan and then drives a coding agent to implement it — keeping your intent reviewable at every stage. Its core competencies: -- **Self-contained binary plus installed agent skills.** A single binary that, on `init`, installs the skills (and commands) your coding agent needs to run the Spektacular workflows. -- **State-machine-driven workflow.** Spec, plan, and implement each run as a stepwise state machine. Spektacular hands the agent one per-step prompt at a time (`new` / `goto` / `steps`), so every stage is resumable — stop, inspect, edit, and resume without losing work. +- **Self-contained binary plus installed agent skills.** A single binary that, on `init`, installs the skills (and commands) your coding agent needs to run the Spek workflows. +- **State-machine-driven workflow.** Spec, plan, and implement each run as a stepwise state machine. Spek hands the agent one per-step prompt at a time (`new` / `goto` / `steps`), so every stage is resumable — stop, inspect, edit, and resume without losing work. - **Agent-agnostic, multi-agent support.** Works with claude, bob, and codex; pick the one your team already uses, or register your own. - **Project knowledge base.** A searchable, layered store of conventions, architecture, gotchas, and learnings that feeds context into planning. -- **Project design documents.** The worked design a feature is built to (an API shape, a user-facing flow, a data format) kept wherever your team already keeps it and referenced by the spec that needs it, so specs stay readable and planning is bound to the design that was agreed. +- **Project design documents.** The worked design a feature is built to (an API shape, a user-facing flow, a data format) kept wherever your team already keeps it and referenced by the spek that needs it, so speks stay readable and planning is bound to the design that was agreed. ## How It Works -Spektacular follows a three-stage workflow — **spec → plan → implement** — each driven step by step by a state machine: +Spek follows a three-stage workflow — **spec → plan → implement** — each driven step by step by a state machine: -1. **Spec.** You write a markdown spec (requirements, constraints, acceptance criteria); `spec new` scaffolds one from a template. +1. **Spec.** You write a markdown spek (requirements, constraints, acceptance criteria); `spec new` scaffolds one from a template. 2. **Plan.** `plan new` explores your codebase, asks clarifying questions, and writes a detailed implementation plan — `plan.md`, `research.md`, and `context.md`. 3. **Implement.** `implement new` drives the coding agent through each phase of the plan and validates the result against your acceptance criteria. -Workflow progress can be inspected without reading Spektacular's state files directly. `spektacular spec status` and `spektacular plan status` keep reporting the single in-progress workflow. Passing an artifact name switches the commands to per-artifact status: +Workflow progress can be inspected without reading Spek's state files directly. `spektacular spec status` and `spektacular plan status` keep reporting the single in-progress workflow. Passing an artifact name switches the commands to per-artifact status: ```bash spektacular spec status spektacular plan status ``` -Both take the bare artifact name with no extension (`000057_git-commit`, not `000057_git-commit.md`), the same name `state.json` records in `data.name`. That bare name is the stable key shared by convention across the spec file, the plan directory and the changelog record; it is the key to join on, and the addressing convention [#46](https://github.com/hivecommons/spektacular/issues/46) proposes for every verb. `plan status ` reports the plan's `plan.md` only, not the plan's other documents. +Both take the bare artifact name with no extension (`20260922132517-a3f9c0de-git-commit`, not `20260922132517-a3f9c0de-git-commit.md`), the same name `state.json` records in `data.name`. The status payload also returns `artifact_id`; external orchestrators should use that field as the join key across spec, plan and changelog artifacts. For new timestamp-generated artifacts `artifact_id` is the timestamp plus random-suffix name. Older counter-prefixed names remain readable aliases during migration, but projects that still choose `spec.id_method: counter` must not treat the numeric counter prefix as globally unique across branches. `plan status ` reports the plan's `plan.md` only, not the plan's other documents. -The named form returns JSON with the artifact kind, name, document status, workflow step when that artifact is currently in progress, completed steps, `created_at`, `closed_at`, and the `spec` / `plan` frontmatter cross-references (surfaced when present, but rarely populated today). Two timestamps are kept apart: `updated_at` is workflow activity and appears only while that artifact has the in-progress workflow, so its absence means nothing is live; `modified_at` is the store's modification time for the artifact and moves on any write, including a checkout or a reformat. Frontmatter dates are stored as `YYYY-MM-DD` and are emitted as RFC3339 midnight UTC timestamps. `spec file list` and `plan file list` carry `modified_at` per entry, so polling many artifacts is one list call. +The named form returns JSON with the artifact kind, name, document status, workflow step when that artifact is currently in progress, completed steps, `created_at`, `closed_at`, and the `spec` / `plan` frontmatter cross-references (surfaced when present, but rarely populated today). Two timestamps are kept apart: `updated_at` is workflow activity and appears only while that artifact has the in-progress workflow, so its absence means nothing is live; `modified_at` is the store's modification time for the artifact and moves on any write, including a checkout or a reformat. Frontmatter dates are stored as `YYYY-MM-DD` and are emitted as RFC3339 midnight UTC timestamps. `spec file list` and `plan file list` carry `modified_at` per entry, so polling many artifacts is one list call. When `plan.strict_spec_changes` is true, `plan status ` reports `document_status: "stale"` and `current_step: "stale"` once the linked spec is modified after a final plan; `implement new` and subsequent implement steps refuse that plan until it is replanned and re-approved. With the default non-strict setting, a later spec edit does not invalidate an existing plan. For the full pipeline, see the [how-it-works documentation](https://spektacular.dev/how-it-works/). ## Install & getting started -Spektacular is a single self-contained Go binary. +Spek is a single self-contained Go binary. ```bash # Homebrew -brew install jumppad-labs/homebrew-repo/spektacular +brew install hivecommons/homebrew-repo/spektacular # Go 1.21+ -go install github.com/jumppad-labs/spektacular@latest +go install github.com/hivecommons/spektacular@latest ``` Or download a pre-built binary from the [releases page](https://github.com/hivecommons/spektacular/releases). See the [install docs](https://spektacular.dev/install/) for apt and other methods. You also need a supported coding agent CLI (claude, bob, or codex) installed and configured. @@ -72,21 +74,21 @@ spektacular plan new --data '{"name":""}' spektacular implement new --data '{"name":""}' ``` -Spec names are normalised and prefixed by the CLI, so use the returned `spec_name` and `spec_path` for follow-up commands rather than the name you passed. +Spek names are normalised and prefixed by the CLI, so use the returned `spec_name` and `spec_path` for follow-up commands rather than the name you passed. -Specs are plain markdown with a small set of structured sections (overview, requirements, constraints, acceptance criteria, and so on), and `spec new` scaffolds the template for you. For the full walkthrough and spec format, see the [getting-started tutorial](https://spektacular.dev/tutorials/getting-started) and the [how-it-works documentation](https://spektacular.dev/how-it-works/). +Speks are plain markdown with a small set of structured sections (overview, requirements, constraints, acceptance criteria, and so on), and `spec new` scaffolds the template for you. For the full walkthrough and spek format, see the [getting-started tutorial](https://spektacular.dev/tutorials/getting-started) and the [how-it-works documentation](https://spektacular.dev/how-it-works/). ## Supported agents -Spektacular ships with three coding-agent integrations. `spektacular init ` runs the chosen agent's install step, writing its workflow skills (and, where the agent has no skill mechanism, command wrappers) into your project: +Spek ships with three coding-agent integrations. `spektacular init ` runs the chosen agent's install step, writing its workflow skills (and, where the agent has no skill mechanism, command wrappers) into your project: -- **claude** — installs the workflow skills under `.claude/skills/` and ensures the project's `CLAUDE.md` imports `@AGENTS.md`, so the Spektacular agent rules take effect. +- **claude** — installs the workflow skills under `.claude/skills/` and ensures the project's `CLAUDE.md` imports `@AGENTS.md`, so the Spek agent rules take effect. - **bob** — installs skills under `.bob/skills/` and command wrappers under `.bob/commands/`. - **codex** — installs skills under `.agents/skills/`. Each integration is deliberately small: an agent implements a narrow `Agent` interface — `Name()` (its CLI identifier) and `Install()` (which writes its workflow artefacts) — and registers itself with the agent package from an `init()` function. Adding a new agent means implementing those two methods and registering the type. -Both the coding agent and the storage layer are pluggable behind defined Go interfaces — the `Agent` interface in `internal/agent` and the `Store` interface in `internal/store` (the read/write/search surface backing the spec, plan, and knowledge stores). Only the `file` store ships today. For the full interface signatures and how to add your own backend or agent, see the [extending documentation](https://spektacular.dev/extending/) and the [plugins overview](https://spektacular.dev/plugins/). +Both the coding agent and the storage layer are pluggable behind defined Go interfaces — the `Agent` interface in `internal/agent` and the `Store` interface in `internal/store` (the read/write/search surface backing the spek, plan, and knowledge stores). Only the `file` store ships today. For the full interface signatures and how to add your own backend or agent, see the [extending documentation](https://spektacular.dev/extending/) and the [plugins overview](https://spektacular.dev/plugins/). ## Project Structure @@ -108,7 +110,7 @@ Running `spektacular init ` creates: └── decisions/ # looked-up: the reasoning behind choices ``` -Each knowledge category directory is scaffolded with a `README.md` describing what belongs in it. By default Spektacular reads `.spektacular/knowledge/` as this repo's own store, addressed by the name the project registered the repo under; the project can declare additional shared stores — for example a `team` directory or a machine-wide `global` one — under `knowledge.sources` (see [Configuration](#configuration)). See [Knowledge](#knowledge) for how it is organised and consumed. +Each knowledge category directory is scaffolded with a `README.md` describing what belongs in it. By default Spek reads `.spektacular/knowledge/` as this repo's own store, addressed by the name the project registered the repo under; the project can declare additional shared stores — for example a `team` directory or a machine-wide `global` one — under `knowledge.sources` (see [Configuration](#configuration)). See [Knowledge](#knowledge) for how it is organised and consumed. ## Knowledge @@ -163,13 +165,13 @@ Every subcommand accepts `--schema` to print its input/output JSON schema and ex ### Capturing knowledge -When research surfaces a durable learning, gotcha, or convention worth keeping, the agent **proposes** the destination — the tier, the store name, and the path — along with the exact content, and waits for your explicit confirmation before writing; it never persists to a knowledge store unprompted. In a Spektacular-initialised repo, the `spek-knowledge` skill is the entry point for reading, contributing to, and updating the knowledge base in any session, and coding agents route what they would otherwise save to their own per-user memory into the project knowledge base instead, so captured knowledge lands in git and travels with the project. +When research surfaces a durable learning, gotcha, or convention worth keeping, the agent **proposes** the destination — the tier, the store name, and the path — along with the exact content, and waits for your explicit confirmation before writing; it never persists to a knowledge store unprompted. In a Spek-initialised repo, the `spek-knowledge` skill is the entry point for reading, contributing to, and updating the knowledge base in any session, and coding agents route what they would otherwise save to their own per-user memory into the project knowledge base instead, so captured knowledge lands in git and travels with the project. ## Configuration -Configuration is split across two files, and a colocated single-repo project simply holds both in the same `.spektacular/` directory. A repo's Spektacular files can also live apart from its code, in a folder that points at the code (see [Repo configuration](#repo-configuration-repoyaml) below). +Configuration is split across two files, and a colocated single-repo project simply holds both in the same `.spektacular/` directory. A repo's Spek files can also live apart from its code, in a folder that points at the code (see [Repo configuration](#repo-configuration-repoyaml) below). -- **`.spektacular/config.yaml` (project configuration).** The project's identity, the coding agent Spektacular drives, the registry of member repos with the location of each repo's Spektacular files, the central `spec`, `plan`, and `changelog` stores, and the design sources the project declares. Spektacular always runs against a project: running it in a directory with no `config.yaml` produces an explicit error pointing at `init` (there is no parent-directory search). +- **`.spektacular/config.yaml` (project configuration).** The project's identity, the coding agent Spek drives, the registry of member repos with the location of each repo's Spek files, the central `spec`, `plan`, and `changelog` stores, and the design sources the project declares. Spek always runs against a project: running it in a directory with no `config.yaml` produces an explicit error pointing at `init` (there is no parent-directory search). - **`.spektacular/repo.yaml` (repo configuration).** A repo's own concerns only: what it is, where its code lives, its knowledge sources, and its changelog provider. It carries no pointer to any project, so one repo can belong to several projects at once. > **Breaking change**: earlier releases used a single `config.yaml` without a project `name`. Existing setups re-initialize with `spektacular init `: init backfills the name (from the directory basename, or `--name`), seeds the colocated repo's `repo.yaml`, and registers it in the new `repos` list. @@ -184,15 +186,17 @@ name: my-project # required, slug-safe; namespaces changelog source: git@example.com:org/my-project.git # optional; the project's git address, recorded in derived changelog entries only command: spektacular agent: claude +auto_commit: "off" # off | workflow | full: automatic git commits (local only) debug: enabled: false spec: provider: file - id_method: timestamp # how new spec identifiers are generated + id_method: timestamp # timestamp + random suffix; counter is legacy and branch-local config: directory: specs # relative to the folder holding config.yaml plan: provider: file + strict_spec_changes: false # true marks final plans stale after later spec edits config: directory: plans # relative to the folder holding config.yaml changelog: @@ -220,7 +224,7 @@ design: location: ../design/api # relative to the folder holding config.yaml; may sit outside the project ``` -Each repo entry needs a slug-safe unique `name` and a `location`: the folder holding that repo's `repo.yaml` (`local` is still accepted and means the same thing). A relative location is resolved from the folder holding `config.yaml`, and nothing is appended to it, so the project's own footprint is `.` and a repo folder in the project is `../repos/`. A repo is normally added through a guided flow: you are asked which repo to add, and its name, description, role and tags are each proposed for you from what the repo says about itself, one question at a time, with a plain-language confirmation before anything is written. Spektacular's files go inside the repo being added unless it cannot take them or you say otherwise, in which case they live in a folder under the project and the repo is left with only its code. An add can be started and finished while a spec or plan is already in progress. A caller that already knows every detail can still register a repo in a single command with `repo add`. Where the code lives is declared in the repo's own `repo.yaml` as `source`; the old `address` key is no longer read, and a config that still carries it fails to load with an error saying where the value now goes. `description`, `role`, and `tags` are optional metadata, also in `repo.yaml`, that cross-repo planning uses to attribute requirements to the right repo. Add to the registry with `spektacular repo new`, or `spektacular repo add` when every detail is already known, and inspect it with `spektacular repo list`; removal is a manual config edit. Cloned repos are never fetched or pulled automatically; a stale clone produces a warning only. +Each repo entry needs a slug-safe unique `name` and a `location`: the folder holding that repo's `repo.yaml` (`local` is still accepted and means the same thing). A relative location is resolved from the folder holding `config.yaml`, and nothing is appended to it, so the project's own footprint is `.` and a repo folder in the project is `../repos/`. A repo is normally added through a guided flow: you are asked which repo to add, and its name, description, role and tags are each proposed for you from what the repo says about itself, one question at a time, with a plain-language confirmation before anything is written. Spek's files go inside the repo being added unless it cannot take them or you say otherwise, in which case they live in a folder under the project and the repo is left with only its code. An add can be started and finished while a spec or plan is already in progress. A caller that already knows every detail can still register a repo in a single command with `repo add`. Where the code lives is declared in the repo's own `repo.yaml` as `source`; the old `address` key is no longer read, and a config that still carries it fails to load with an error saying where the value now goes. `description`, `role`, and `tags` are optional metadata, also in `repo.yaml`, that cross-repo planning uses to attribute requirements to the right repo. Add to the registry with `spektacular repo new`, or `spektacular repo add` when every detail is already known, and inspect it with `spektacular repo list`; removal is a manual config edit. Cloned repos are never fetched or pulled automatically; a stale clone produces a warning only. **Relative locations everywhere in `config.yaml` share one base: the folder holding `config.yaml`.** That covers a repos entry's `location`, a `knowledge.sources` entry's `config.location`, a `design.sources` entry's `config.location`, and the `spec`, `plan` and `changelog` store directories, so `..` is the project's own root and `../team-kb` a folder beside it. The store directories default to `specs`, `plans` and `changelog`, which land in `.spektacular/specs`, `.spektacular/plans` and `.spektacular/changelog`; a store directory outside the project is refused with the corrected value to write. An absolute location is used as written. A knowledge source that does not resolve to a directory fails fast, naming the store, the path it resolved to, and the base it resolved from; when the store is found where the pre-1.0 rule would have put it, the error also names the exact corrected value to write. A design source behaves the same way and fails fast with the same three facts, with one deliberate difference from the store directories: a design source's location is allowed to resolve outside the project, and is written back exactly as declared rather than re-expressed, because a design source points at a folder the team already keeps. @@ -246,7 +250,7 @@ changelog: directory: changelog # where this repo's derived entries land ``` -A repo's Spektacular files can sit inside its code, in a `.spektacular/` folder holding `repo.yaml` with a file source pointing at `..`, or in a folder of their own, for example one folder per repo under a project, with `source` pointing at a checkout on disk (absolute, relative to the folder holding `repo.yaml`, or using `${VAR}`) or at a git repository that Spektacular clones into `.spektacular/repos//` on first use. In the separate layout the code repository receives only code changes; knowledge and changelog entries land under the folder holding `repo.yaml`. `spektacular repo list` reports the resolved source as each repo's `root`. See [Multi-Repo Projects](https://spektacular.dev/projects/) for the layouts. +A repo's Spek files can sit inside its code, in a `.spektacular/` folder holding `repo.yaml` with a file source pointing at `..`, or in a folder of their own, for example one folder per repo under a project, with `source` pointing at a checkout on disk (absolute, relative to the folder holding `repo.yaml`, or using `${VAR}`) or at a git repository that Spek clones into `.spektacular/repos//` on first use. In the separate layout the code repository receives only code changes; knowledge and changelog entries land under the folder holding `repo.yaml`. `spektacular repo list` reports the resolved source as each repo's `root`. See [Multi-Repo Projects](https://spektacular.dev/projects/) for the layouts. Knowledge aggregates across every registered repo's declared sources (in registry order) followed by the project-owned sources, so a repo's knowledge travels with it into every project that registers it. Changelog entries, central and derived per-repo, are namespaced under a folder named after the project (`//_.md`), so multiple projects writing into one repo can never collide. @@ -263,13 +267,13 @@ An upgrade brings `config.yaml` and every registered repo's `repo.yaml` present ### Excluding paths (`.spektacular_ignore`) -Any source root (a repo, or the project's own storage locations) may carry a `.spektacular_ignore` file using gitignore pattern syntax. Matching paths are excluded from Spektacular's own listing and search results, keeping build artifacts and dependency directories out of planning research, but a directly named path is never blocked, and agents' native file tools are unaffected. +Any source root (a repo, or the project's own storage locations) may carry a `.spektacular_ignore` file using gitignore pattern syntax. Matching paths are excluded from Spek's own listing and search results, keeping build artifacts and dependency directories out of planning research, but a directly named path is never blocked, and agents' native file tools are unaffected. For the full reference (every key, the id-method semantics, name-normalisation rules, and `${VAR}` expansion) see the [configuration documentation](https://spektacular.dev/configuration/). For the concept of multi-repo projects, why the configuration is split this way, and how work is attributed across repos, see [Multi-Repo Projects](https://spektacular.dev/projects/). ## Testing -Spektacular has two layers of tests: a fast Go unit suite, and an end-to-end [Harbor](https://harborframework.com/) harness that runs the workflows against real AI coding agents inside sandboxed Docker containers. +Spek has two layers of tests: a fast Go unit suite, and an end-to-end [Harbor](https://harborframework.com/) harness that runs the workflows against real AI coding agents inside sandboxed Docker containers. ### Unit tests @@ -355,7 +359,7 @@ tests/harbor/jobs// The repo-workflow suite is the one whose assertions are about the conversation rather than the files: that only the repo itself is asked for cold, that every later question carries a proposed -value, that the questions arrive one per exchange, and that none of Spektacular's internal +value, that the questions arrive one per exchange, and that none of Spek's internal vocabulary reaches the user. Its rules are themselves checked by `tests/harbor/repo-workflow/tests/test_verifier_selfcheck.py`, which runs locally under plain pytest with no container and proves each rule fails on a transcript that breaks it: diff --git a/docs/content/spektacular/unknown-criteria.md b/docs/content/spektacular/unknown-criteria.md index fe5f852..dd4a01a 100644 --- a/docs/content/spektacular/unknown-criteria.md +++ b/docs/content/spektacular/unknown-criteria.md @@ -14,17 +14,17 @@ sometimes I do not have a clear idea of what the criteria for the work are. Broadly I think most of the activities that I carry out when coding fall into the following three categories: -1. I know what the criteria for the work are, and I can write a specification for +1. I know what the criteria for the work are, and I can write a spek for it. 2. Small bugs or minor changes where I have a fair idea of the problem and the solution. 3. Something is wrong and I don't know what the problem is or what the solution is. -In the first case, I can use the Spektacular workflow to write a specification +In the first case, I can use the Spektacular (Spek) workflow to write a spek and then implement it. In the second case, vibe coding is probably appropriate, and way quicker than writing a specification. In the third case, the temptation is to start working with the agent to investigate and fix the problem. However, -all of the detail around this work is not captured in a specification and plan +all of the detail around this work is not captured in a spek and plan and so it may not adhere to the team's coding standards and practices, and the code that is produced may not be maintainable or testable. I am basically vibe coding my way to another problem. @@ -32,8 +32,8 @@ coding my way to another problem. ## A bug in Spektacular Let's look at a concrete example. I was recently working on what I believed to be -a bug in Spektacular when using the `new` mode to create specifications with -the Bob agent. The way that Spektacular works is that internally the skills are +a bug in Spek when using the `new` mode to create specifications with +the Bob agent. The way that Spek works is that internally the skills are deliberately very simple: they only instruct the agent to do a single task. Further instructions are provided to the agent once it has completed the task. By following this approach, and using a state machine to control the flow of the @@ -64,7 +64,7 @@ and if everything is valid, it returns the next prompt. What I saw was that Bob was trying to call the goto command, but with a completely incorrect step. -Having an understanding of how Spektacular works, I did a little manual poking +Having an understanding of how Spek works, I did a little manual poking through the codebase looking for any obvious problems, but I could not find anything. Next, I turned to my coding agent. @@ -92,7 +92,7 @@ run: spec goto --data '{"step":"requirements"}' Now, experience and seeing the issue firsthand makes me think that this is probably what happened. The temptation is to just accept the fix and move on: -this code change probably does not require a specification and a plan, and in +this code change probably does not require a spek and a plan, and in reality, I could change the code myself in about 30 seconds. But experience also tells me that this is not the end of the story: my gut tells me that there is more than one error message like this in the codebase. So let's ask @@ -117,21 +117,21 @@ Let's look at all errors across the entire codebase where an error is surfaced t ``` The agent now goes away and does quite a bit more work, and the reality is -that it finds that most of the errors surfaced by Spektacular are not very +that it finds that most of the errors surfaced by Spek are not very helpful. It is also quite a bit of work that should be fixed with SDD, not -just a quick fix. So, let's get the agent to write a full specification for +just a quick fix. So, let's get the agent to write a full spek for this work; we can then review it and implement it. ```markdown -We should write a specification using the spek-new skill that ensures all error +We should write a spek using the spek-new skill that ensures all error messages emitted from the system are meaningful to an AI agent and which provide enough diagnostic information to allow it to find a solution. ``` -## Writing the specifications +## Writing the speks -The agent then uses the skill and creates a specification. Upon reviewing this -specification, one of the Non-Goals actually surfaces something interesting, +The agent then uses the skill and creates a spek. Upon reviewing this +spek, one of the Non-Goals actually surfaces something interesting, something I had been thinking about myself. ```markdown @@ -142,7 +142,7 @@ is out of scope; it is left for a separate, future spec. ``` So, whilst there is context for all of this, let's get the agent to write a -specification for what it thinks would be a useful debug or session logging +spek for what it thinks would be a useful debug or session logging feature. ```markdown @@ -151,25 +151,25 @@ should ensure that the output from the logging prioritises agent consumption over human consumption. ``` -We now have two new specifications that improve both the error logging and -the diagnostic information that Spektacular produces, both of which will make +We now have two new speks that improve both the error logging and +the diagnostic information that Spek produces, both of which will make it easier to fix future problems. -I can now share these specifications with the team to get their feedback before +I can now share these speks with the team to get their feedback before I go ahead and implement them. ## Conclusion In this article, we have seen how we can work with the agent to investigate a -problem and then use the agent to write a specification for the work that needs +problem and then use the agent to write a spek for the work that needs to be completed. In this particular instance, starting with Spec Driven Development would not have been helpful, as I did not have a clear idea of the -problem or enough information to write a specification. However, by using the +problem or enough information to write a spek. However, by using the agent to investigate and determine scope and potential root cause, it then -turns the activity of writing the specification into a trivial task of asking +turns the activity of writing the spek into a trivial task of asking the agent to do it. Not all tasks require spec driven development, and spec driven development is not always the best starting approach; however, the workflow is flexible: you can always start ad hoc and end up with the quality and maintainability of a -specification and plan. +spek and plan. diff --git a/public/llms.txt b/public/llms.txt index ec3baf6..1435253 100644 --- a/public/llms.txt +++ b/public/llms.txt @@ -6,6 +6,8 @@ Canonical integrations page: https://docs.hivecommons.dev/docs/hive/integrations Hive supports Claude Code, GitHub Copilot CLI, Goose, OpenAI Codex CLI, Pi, IBM Bob, Aider, Gemini CLI, Google Antigravity CLI, OpenCode, Kilo Code, Muse Code, Oh My Pi, vLLM, llm-d, LiteLLM, IBM watsonx.ai, OpenRouter, Anthropic, OpenAI and DeepSeek. +Spektacular (Spek) is Hive Commons' spec-driven workflow tool; the specs it produces are called speks. + ## Infrastructure thanks Hive Commons thanks Akamai (Linode), Oracle Cloud (OKE), Cloudflare, GitHub Copilot and Bluehost. diff --git a/scripts/sync-sibling-docs.ts b/scripts/sync-sibling-docs.ts index 8ba1fe0..f0f6fa6 100644 --- a/scripts/sync-sibling-docs.ts +++ b/scripts/sync-sibling-docs.ts @@ -138,6 +138,140 @@ export const PROJECTS: ProjectSync[] = [ }, ]; + + +// --------------------------------------------------------------------------- +// Spek naming style +// --------------------------------------------------------------------------- +// Keep canonical command names, paths, and stage identifiers unchanged while the +// docs site introduces the Spek nickname in rendered prose. +export function introduceSpekStyle(project: string, target: string, content: string): string { + if (project !== "spektacular") return content; + + const replacementsByTarget: Record> = { + "readme.md": [ + ["# Spektacular\n\nAgent-agnostic CLI tool for spec-driven development, providing skills and integrations for coding agents (Claude, Bob, Codex) to plan and implement work from a written spec.", "# Spektacular\n\n> Spektacular — Spek for short. The specs it produces are called speks.\n\nAgent-agnostic CLI tool for spec-driven development, providing skills and integrations for coding agents (Claude, Bob, Codex) to plan and implement work from a written spek."], + ["## What is Spektacular?\n\nSpektacular is a self-contained Go binary", "## What is Spektacular?\n\nSpek is a self-contained Go binary"], + ["Spektacular turns it into", "Spek turns it into"], + ["You write a markdown spec (requirements", "You write a markdown spek (requirements"], + ["Spektacular is a single self-contained Go binary.", "Spek is a single self-contained Go binary."], + ["run the Spektacular workflows", "run the Spek workflows"], + ["Spec, plan, and implement each run", "Spec, plan, and implement each run"], + ["Spektacular hands the agent", "Spek hands the agent"], + ["referenced by the spec that needs it, so specs stay readable", "referenced by the spek that needs it, so speks stay readable"], + ["Spektacular follows a three-stage workflow", "Spek follows a three-stage workflow"], + ["You write a markdown specification; Spek turns it into", "You write a markdown spek; Spek turns it into"], + ["scaffolds one from a template", "scaffolds one from a template"], + ["reading Spektacular's state files", "reading Spek's state files"], + ["across the spec file, the plan directory and the changelog record", "across the spek file, the plan directory and the changelog record"], + ["Spec names are normalised", "Spek names are normalised"], + ["Specs are plain markdown", "Speks are plain markdown"], + ["full walkthrough and spec format", "full walkthrough and spek format"], + ["Spektacular ships with three", "Spek ships with three"], + ["so the Spektacular agent rules take effect", "so the Spek agent rules take effect"], + ["backing the spec, plan, and knowledge stores", "backing the spek, plan, and knowledge stores"], + ["By default Spektacular reads", "By default Spek reads"], + ["In a Spektacular-initialised repo", "In a Spek-initialised repo"], + ["A repo's Spektacular files", "A repo's Spek files"], + ["Spektacular always runs against a project", "Spek always runs against a project"], + ["Spektacular's files go inside", "Spek's files go inside"], + ["git repository that Spektacular clones", "git repository that Spek clones"], + ["coding agent Spektacular drives", "coding agent Spek drives"], + ["location of each repo's Spektacular files", "location of each repo's Spek files"], + ["the central `spec`, `plan`, and `changelog` stores", "the central `spec`, `plan`, and `changelog` stores"], + ["written by Spektacular", "written by Spektacular"], + ["new Spektacular", "new Spektacular"], + ["until the project is brought up to date", "until the project is brought up to date"], + ["older than the running Spektacular", "older than the running Spektacular"], + ["Settings written by a *newer* Spektacular", "Settings written by a *newer* Spektacular"], + ["Spektacular's own listing", "Spek's own listing"], + ["Spektacular has two layers", "Spek has two layers"], + ["none of Spektacular's internal", "none of Spek's internal"], + ], + "getting-started.md": [ + ["_Take a feature from a rough idea to working code using a Spektacular spec,", "_Take a feature from a rough idea to working code using a Spektacular (Spek) spek,"], + ["In this tutorial you will see how Spektacular's", "In this tutorial you will see how Spek's"], + ["coding agent Spektacular supports", "coding agent Spek supports"], + ["## What is Spektacular\n\nSpektacular is a CLI", "## What is Spektacular\n\nSpek is a CLI"], + ["store your specs and knowledge base", "store your speks and knowledge base"], + ["# scaffold a new specification", "# scaffold a new specification"], + ["turn a spec into", "turn a spek into"], + ["agent state: the spec, the plan", "agent state: the spek, the plan"], + ["### Step 2: Install Spektacular\n\nSpektacular is a Go binary", "### Step 2: Install Spektacular\n\nSpek is a Go binary"], + ["Spektacular drives an external", "Spek drives an external"], + ["outside Spektacular before continuing", "outside Spek before continuing"], + ["use Spektacular with", "use Spek with"], + ["want Spektacular to\noperate on", "want Spek to\noperate on"], + ["so Spektacular knows", "so Spek knows"], + ["The specification in Spektacular\nserves", "The spek in Spek\nserves"], + ["The specification in the Spektacular workflow", "The spek in the Spek workflow"], + ["The content in these sections guides", "The content in these sections guides"], + ["the specification pays off", "the spek pays off"], + ["The spec also serves", "The spek also serves"], + ["Scaffold a new specification", "Scaffold a new spek"], + ["Spektacular will automatically create", "Spek will automatically create"], + ["Spektacular writes all temporary", "Spek writes all temporary"], + ["file name for the spec", "file name for the spek"], + ["The way Spektacular works", "The way Spek works"], + ["Spektacular invokes `codex`", "Spek invokes `codex`"], + ["Spektacular\ninvokes `codex`", "Spek\ninvokes `codex`"], + ["call the Spektacular CLI", "call the Spektacular CLI"], + ["creating the spec file", "creating the spek file"], + ["an empty spec will be created", "an empty spek will be created"], + ["sections of the spec", "sections of the spek"], + ["final specification or plan", "final spek or plan"], + ["current specification and the answers", "current spek and the answers"], + ["final section of the specification", "final section of the spek"], + ["verify the specification before writing", "verify the spek before writing"], + ["pass over the specification", "pass over the spek"], + ["the specification is well formed", "the spek is well formed"], + ["generate your full specification", "generate your full spek"], + ["judge the spec the", "judge the spek the"], + ["writing the spec to", "writing the spek to"], + ["Select the spec you just created", "Select the spek you just created"], + ["review the final specification", "review the final spek"], + ["When reviewing the specification", "When reviewing the spek"], + ["edit the spec directly", "edit the spek directly"], + ["Spektacular gives you", "Spek gives you"], + ["learn how Spektacular\nsupports", "learn how Spek\nsupports"], + ["Spektacular queries every store", "Spek queries every store"], + ["As with the specification", "As with the spek"], + ["name of the specification", "name of the spek"], + ["from the specification or the context", "from the spek or the context"], + ["retrieved from the specification and the context", "retrieved from the spek and the context"], + ["The spec defines no success metrics", "The spec defines no success metrics"], + ["using the Spec Driven Development workflow", "using the Spec Driven Development workflow"], + ["The specification and plan", "The spek and plan"], + ], + "unknown-criteria.md": [ + ["In the first case, I can use the Spektacular workflow", "In the first case, I can use the Spektacular (Spek) workflow"], + ["a bug in Spektacular when", "a bug in Spek when"], + ["The way that Spektacular works", "The way that Spek works"], + ["how Spektacular works", "how Spek works"], + ["surfaced by Spektacular are", "surfaced by Spek are"], + ["full specification for\nthis work", "full spek for\nthis work"], + ["Writing the specifications", "Writing the speks"], + ["creates a specification", "creates a spek"], + ["this\nspecification", "this\nspek"], + ["write a\nspecification for", "write a\nspek for"], + ["two new specifications", "two new speks"], + ["diagnostic information that Spektacular produces", "diagnostic information that Spek produces"], + ["share these specifications", "share these speks"], + ["write a specification for the work", "write a spek for the work"], + ["a specification and a plan", "a spek and a plan"], + ["turns the activity of writing the specification", "turns the activity of writing the spek"], + ["write a specification", "write a spek"], + ["specification and plan", "spek and plan"], + ], + }; + + let result = content; + for (const [from, to] of replacementsByTarget[target] ?? []) { + result = result.replaceAll(from, to); + } + return result; +} + // --------------------------------------------------------------------------- // Brand scrub // --------------------------------------------------------------------------- @@ -308,7 +442,7 @@ async function main() { continue; } const page = await renderPage(p, f, body, outDir); - const out = syncedHeader(p, f) + normalizeFences(scrubLegacyBranding(page)); + const out = syncedHeader(p, f) + normalizeFences(scrubLegacyBranding(introduceSpekStyle(p.project, f.target, page))); fs.writeFileSync(path.join(outDir, f.target), out); console.log(`synced ${p.project}/${f.target} <- ${r.owner}/${r.repo}/${f.source}`); } diff --git a/src/app/docs/[...slug]/page.tsx b/src/app/docs/[...slug]/page.tsx index aabde34..fc5889e 100644 --- a/src/app/docs/[...slug]/page.tsx +++ b/src/app/docs/[...slug]/page.tsx @@ -60,7 +60,7 @@ function integrationsJsonLd() { description: INTEGRATIONS_DESCRIPTION, url: 'https://docs.hivecommons.dev/docs/hive/integrations', about: INTEGRATION_NAMES.map((name) => ({ '@type': 'SoftwareApplication', name })), - keywords: INTEGRATION_NAMES.join(', '), + keywords: [...INTEGRATION_NAMES, 'Spektacular', 'Spek', 'speks'].join(', '), publisher: { '@type': 'Organization', name: 'Hive Commons', @@ -76,7 +76,7 @@ function integrationsJsonLd() { license: 'https://www.apache.org/licenses/LICENSE-2.0', url: 'https://hive.hivecommons.dev/', codeRepository: 'https://github.com/hivecommons/hive', - keywords: INTEGRATION_NAMES.join(', '), + keywords: [...INTEGRATION_NAMES, 'Spektacular', 'Spek', 'speks'].join(', '), featureList: [ 'Drives supported agent CLI backends including Claude Code, GitHub Copilot CLI, Goose, OpenAI Codex CLI, IBM Bob, Gemini CLI and more.', 'Routes inference through supported engines and gateways including vLLM, llm-d, LiteLLM, IBM watsonx.ai, OpenRouter, Anthropic, OpenAI and DeepSeek.', diff --git a/src/app/docs/layout.tsx b/src/app/docs/layout.tsx index 9ff11a4..dbc9a92 100644 --- a/src/app/docs/layout.tsx +++ b/src/app/docs/layout.tsx @@ -28,7 +28,7 @@ const jetbrainsMono = JetBrains_Mono({ const SITE_URL = 'https://docs.hivecommons.dev' const SITE_TITLE = 'Hive Commons Docs - AI Agent Collaboration Projects' const SITE_DESCRIPTION = - 'Documentation for Hive Commons projects that help AI coding agents and maintainers work together: Hive, Spektacular, hotshot, pluk, promptargs, rationguard, and dibs.' + 'Documentation for Hive Commons projects that help AI coding agents and maintainers work together: Hive, Spektacular (Spek), hotshot, pluk, promptargs, rationguard, and dibs.' const INTEGRATION_NAMES = [ 'Claude Code', @@ -54,6 +54,8 @@ const INTEGRATION_NAMES = [ 'DeepSeek', ] +const DOCS_KEYWORDS = [...INTEGRATION_NAMES, 'Spektacular', 'Spek', 'speks'] + const INFRA_SPONSORS = [ { '@type': 'Organization', name: 'Akamai', url: 'https://www.linode.com/' }, { '@type': 'Organization', name: 'Oracle Cloud', url: 'https://www.oracle.com/cloud/cloud-native/kubernetes-engine/' }, @@ -78,6 +80,22 @@ const DOCS_JSON_LD = [ 'Routes inference through supported engines and gateways including vLLM, llm-d, LiteLLM, IBM watsonx.ai, OpenRouter, Anthropic, OpenAI and DeepSeek.', ], }, + { + '@context': 'https://schema.org', + '@type': 'SoftwareApplication', + name: 'Spektacular', + alternateName: 'Spek', + applicationCategory: 'DeveloperApplication', + operatingSystem: 'Linux, macOS', + license: 'https://www.apache.org/licenses/LICENSE-2.0', + url: 'https://spektacular.dev/', + codeRepository: 'https://github.com/hivecommons/spektacular', + keywords: ['Spektacular', 'Spek', 'speks', 'spec-driven development', 'AI coding agents'].join(', '), + featureList: [ + 'Turns a markdown spek into a reviewed implementation plan.', + 'Drives coding agents through resumable spec, plan, and implement workflows.', + ], + }, { '@context': 'https://schema.org', '@type': 'Organization', @@ -94,6 +112,7 @@ export const metadata: Metadata = { template: '%s | Hive Commons Docs', }, description: SITE_DESCRIPTION, + keywords: DOCS_KEYWORDS, metadataBase: new URL(SITE_URL), alternates: { canonical: '/docs',