setup
/setup
Use when initializing Beat or updating its config — not for editing config.yaml directly or non-Beat tools
- Author
- kirkchen ↗
- Repository
- beat ↗
- Licence
- MIT
- Last repository change
- 28.09.2026
Assessment and security
- Files in this package
- 5
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 1
No signals detected. Repository changed on 28.09.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Use when initializing Beat or updating its config — not for editing config.yaml directly or non-Beat tools
Original author description
Use when initializing Beat or updating its config — not for editing config.yaml directly or non-Beat tools
How it works
SKILL.md has no level-two headings · 208 lines, 1,107 words
SKILL.md preview
---
name: setup
description: Use when initializing Beat or updating its config — not for editing config.yaml directly or non-Beat tools
---
Initialize Beat configuration in the current project.
<decision_boundary>
**Use for:**
- Setting up Beat for the first time in a project
- Updating existing Beat configuration (language, testing frameworks, rules)
- Detecting project tech stack and recommending test frameworks
**NOT for:**
- Editing `beat/config.yaml` directly (just edit the file)
- Configuring non-Beat tools or project settings
- Creating changes or writing feature files (use `/beat:design`)
**Trigger examples:**
- "Set up Beat" / "Initialize Beat" / "Configure Beat for this project" / "Update Beat config"
- Should NOT trigger: "edit config.yaml" / "design a feature" / "create a change"
</decision_boundary>
**Input**: None required. The skill gathers information interactively.
**Steps**
1. **Check if config already exists**
Check if `beat/config.yaml` exists.
- If yes: read it, show current config, ask if user wants to update or keep it
- If no: proceed to creation
2. **Check superpowers dependency**
Check if the superpowers plugin is available by looking for any `superpowers:*` skill in the skill list.
**If not available:**
> "Beat works standalone, but is better with [superpowers](https://github.com/obra/superpowers) — it provides structured brainstorming, TDD discipline, task decomposition, and git worktree isolation.
>
> Install with: `/plugin marketplace add obra/superpowers`
>
> Without it, Beat falls back to simpler built-in flows."
Use **AskUserQuestion tool**:
1. "Install now" -- run the install command
2. "Continue without it"
**If available:** proceed silently.
3. **Ask artifact language**
Use **AskUserQuestion tool**:
> "What language should Beat use for artifacts (proposals, features, designs, tasks)?"
Provide options:
1. "English (en)" -- default
2. "繁體中文 (zh-TW)"
3. "简体中文 (zh-CN)"
4. Other -- let user specify a BCP 47 tag
This sets the `language` field in config.
4. **Gather project context and detect tech stack**
Use **AskUserQuestion tool** to ask:
> "Describe your project so Beat can tailor its artifacts. Include: tech stack, test framework, and any key conventions."
Provide example options:
1. "Let me describe it" -- open-ended input
2. "Detect from codebase" -- agent scans package.json, Cargo.toml, go.mod, etc.
**If user chooses detection:**
- Scan common manifest files for tech stack and primary language
- Look for test configuration (vitest.config, jest.config, pytest.ini, etc.)
- Look for BDD runner configuration (cucumber.js, behave.ini, etc.)
- Look for e2e configuration (playwright.config, cypress.config, etc.)
- Check for linter/formatter configs
- Summarize findings and confirm with user
**Record the detected/described tech stack** — this informs Step 5 framework recommendations.
5. **Configure test frameworks**
Based on the tech stack from Step 4, recommend appropriate frameworks.
**Step 5a: Ask project type**
Use **AskUserQuestion tool**:
> "What type of project is this?"
1. "Web app (has UI)" -- needs browser automation for e2e
2. "API server" -- needs HTTP client for e2e
3. "CLI tool" -- needs process execution for e2e
4. "Library / SDK" -- e2e usually not needed, behavior tests suffice
**Step 5b: Recommend frameworks using the table below**
Cross-reference (language × project type) to recommend a framework pair. Present as defaults the user can accept or customize:
> "Based on your stack ({language} + {project type}), recommended test frameworks:
> - **Behavior tests:** {recommendation}
> - **E2E tests:** {recommendation}
>
> Accept defaults or customize?"
**Framework recommendation table:**
*Behavior test frameworks (UT / integration):*
| Language | Primary | Alternative |
|----------|---------|-------------|
| TypeScript / JavaScript | vitest | jest |
| Python | pytest | pytest-bdd |
| Go | go test | — |
| Java | JUnit | TestNG |
| C# | xUnit | NUnit |
| Ruby | RSpec | — |
| Rust | cargo test | — |
*E2E frameworks (BDD runner + driver, by project type):*
| Language | Web app (UI) | API server | CLI tool |
|----------|-------------|------------|----------|
| TS / JS | cucumber-js + playwright | cucumber-js + supertest | cucumber-js + execa |
| Python | behave + playwright | behave + requests | behave + subprocess |
| Go | godog + playwright | godog + net/http | godog + os/exec |
| Java | Cucumber-JVM + Selenium | Cucumber-JVM + RestAssured | Cucumber-JVM + ProcessBuilder |
| C# | Reqnroll + Playwright | Reqnroll + HttpClient | Reqnroll + Process |
| Ruby | Cucumber + Capybara | Cucumber + Faraday | Cucumber + Open3 |
For **Library** projects: omit `testing.e2e` — behavior tests are sufficient. Note this in the summary.
**Step 5c: Escape hatch**
If the user explicitly says tests are not needed (e.g., pure docs, config-only, infra project):
- Set `testing.required: false`
- Do NOT push back — respect the user's judgment
This sets the `testing` field in config:
```yaml
testing:
behavior: <selected framework> # always set (unless testing.required: false)
e2e: <selected BDD runner + driver> # set unless Library type or testing.required: false
```
6. **Ask about artifact rules** (optional)
Use **AskUserQuestion tool**:
> "Want to set rules for how artifacts are generated?"
1. "Yes, let me specify" -- ask per-artifact rules (`proposal`, `gherkin`, `design`, `tasks`, and `adr` for ADRs written at any trigger point)
2. "Skip for now" -- create config with context only
If `docs/adr/TEMPLATE.md` already exists, mention that skills will use it as the ADR skeleton automatically — `rules.adr` is for constraints beyond the template (e.g. an index to update).
7. **Write config**
Create `beat/config.yaml` following the schema in `references/config-schema.md`.
```bash
mkdir -p beat
```
Write the file with the gathered context and rules.
8. **Create directory structure** (if not exists)
```bash
mkdir -p beat/changes
mkdir -p beat/features
```
Do **not** create the three living-doc surfaces here. `beat/CONTEXT.md`,
`docs/adr/`, and `beat/ARCHITECTURE.md` (plus module READMEs) are **lazy** —
they appear the first time a Beat skill needs them. A small project may
never need any of them. Mention this in the summary so the user knows
what to expect.
9. **Show summary**
```
## Beat Initialized
**Config:** beat/config.yaml
**Directories:** beat/changes/, beat/features/
**Superpowers:** installed / not installed (fallback mode)
**Testing:** {behavior framework} + {e2e framework} (or "not required")
Your config will be used when creating artifacts.
Edit beat/config.yaml anytime to update preferences.
Beat will also lazy-create three living-doc surfaces when first needed:
- beat/CONTEXT.md — domain glossary (see references/context-format.md)
- docs/adr/ — ADRs, three-condition gate (see references/adr-format.md)
- beat/ARCHITECTURE.md + module READMEs (see references/architecture-format.md)
Small projects may never need any of these.
Ready to start? Run `/beat:design` or `/beat:explore`
```
**Guardrails**
- Never overwrite existing config without asking
- Config is always optional -- if user wants minimal setup, just create directories
- Validate config against `references/config-schema.md` before writing
- Context should be concise -- warn if it exceeds 2KB (soft limit, 50KB hard limit)
- Framework recommendations are suggestions -- always let the user override
- Do not insist on e2e for Library projects
Files in this package (5)
- SKILL.md 8 KB
- references/adr-format.md 8 KB
- references/architecture-format.md 8 KB
- references/config-schema.md 7 KB
- references/context-format.md 8 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · kirkchen/beat | 92 | MIT |
| HwangSlater/harness-fit | 100 | MIT |
| nesquikm/dev-process-toolkit | 100 | MIT |
| userKael/rastro | 100 | MIT |
| als-apg/osprey | 100 | BSD-3-Clause |
| dedujeong/gemba | 100 | Apache-2.0 |
| eigenwise/eigenwise-toolshed | 100 | MIT |
| awrshift/agent-memory-kit | 100 | MIT |
| lifecycle-innovations-limited/claude-ops | 100 | MIT |
Database snapshot: 13.11.2026 · package version 96912f8ac7f6 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90harness-setup
Use when initializing or upgrading Oh My Harness configuration for a Codex project. - 90yaml
Create and review YAML files with safe indentation, schema-aware structure, and low-surprise serialization. Use when editing YAML config or workflow files. - 100create-yaml-tests
Create, update, and repair local Shiplight YAML E2E tests. Use for Shiplight test projects, including project setup, specs, auth setup, YAML implementation, validation, and test maintenance. - 100yaml-config
Use this skill when reading or writing YAML configuration files, loading vehicle parameters, or handling config file parsing with proper error handling. - 100plan
Use when breaking down a Beat change spec into tasks — not for spec creation or implementation - 90openspec-bootstrap
Use when setting up OpenSpec in a repo for the first time, or editing a repo's `openspec/config.yaml`