Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .github/workflows/validate.yml
Original file line number Diff line number Diff line change
Expand Up @@ -45,3 +45,5 @@ jobs:
run: python3 -m unittest discover -s skills/kb-m3e/tests -v
- name: Test kb-engineering (structure and helper)
run: python3 -m unittest discover -s skills/kb-engineering/tests -v
- name: Test setup (config structure)
run: python3 -m unittest discover -s skills/setup/tests -v
84 changes: 10 additions & 74 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ git clone https://github.com/Conava/claude-devline.git
claude --plugin-dir ./claude-devline
```

Then run `/devline:setup` in your project. It creates a `CLAUDE.md` (project context for agents) and a `.claude/devline.local.md` (pipeline settings) through an interactive walkthrough.
Then run `/devline:setup` in your project. It creates a `CLAUDE.md` (project context for agents) and, if you want them, the [config files](#configuration) through an interactive walkthrough.

### Requirements

Expand Down Expand Up @@ -159,7 +159,7 @@ flowchart LR
<details>
<summary><strong>Stage 0: Branch Setup</strong> (automatic)</summary>

Reads branching config from `.claude/devline.local.md`. If you're on a protected branch (main, master, develop, release, production, staging), it creates a feature branch using your configured format (default: `feat/your-feature-name`). Sets up the `.devline/` working directory and, if git does not already ignore it, adds it to `.git/info/exclude` so no tracked file changes.
Reads the branching settings from your [config](#configuration). If you're on a protected branch (main, master, develop, release, production, staging), it creates a feature branch using your configured format (default: `feat/your-feature-name`). Sets up the `.devline/` working directory and, if git does not already ignore it, adds it to `.git/info/exclude` so no tracked file changes.

If a previous pipeline left artifacts behind, it detects them and asks whether to resume or start fresh.

Expand Down Expand Up @@ -514,7 +514,7 @@ Captures (stills, scroll or scripted recordings, frame-change report, page error

Messages follow the `writing` skill. The body says why the change was needed and what it does at a level the code doesn't show, and never restates the diff. The PR body follows the repo's PR template when there is one. Otherwise it has a short `## Description` (what and why: intended effect, use case, issue), then the technical details (how it works, trade-offs, notable effects, closed issues), screenshots for UI changes, and a short `## Verification` only when it is needed.

The skill never pushes to a protected branch without asking and never force-pushes on its own. It uses `--force-with-lease` only when you ask. It never merges. New branch names follow `branch_format` and `branch_kinds` (see [Branching strategy](#branching-strategy)).
The skill never pushes to a protected branch without asking and never force-pushes on its own. It uses `--force-with-lease` only when you ask. It never merges. New branch names follow `branch_format` and `branch_kinds` (see [Configuration](#configuration)).

---

Expand Down Expand Up @@ -552,87 +552,23 @@ The `/graphic-design` skill covers logo design (55 styles), corporate identity p

## Configuration

Create `.claude/devline.local.md` with YAML frontmatter, or run `/devline:setup` for guided setup. Every setting is optional -- defaults work out of the box.
Every setting is optional; the defaults work out of the box. Two files can override them, each with flat YAML frontmatter and optional prose below it for rules no key can say:

### Quick examples
- **Repo:** `.claude/devline.md`, committed. Project rules: branch naming, git policy, testing approach, design mode.
- **User:** `${CLAUDE_CONFIG_DIR:-~/.claude}/devline/config.md`. Personal preferences across repos: models, voice, what AI may do.

**Auto-approve everything (for when you trust the pipeline):**
```yaml
---
auto_approve_brainstorm: true
auto_approve_plan: true
---
```
Each key comes from the first place that sets it: your request, then the repo file, then the user file, then the plugin default.

**Jira branch naming:**
```yaml
---
branch_format: "PROJ-{ticket}/{title}"
branch_kinds: "PROJ"
test_depth: focused
---
```

**Always take the fast lane for small changes:**
```yaml
---
fast_lane: always
---
Squash-merge every PR. Open a PR for every change.
```

<details>
<summary><strong>All settings</strong></summary>

#### Pipeline gates

| Setting | Default | Description |
|---------|---------|-------------|
| `auto_approve_brainstorm` | `false` | Skip approval after brainstorming |
| `auto_approve_plan` | `false` | Skip approval after planning |
| `fast_lane` | `auto` | Fast-lane small changes to implement -> review -> commit. `auto` = detect, `always` = force, `off` = always run the full pipeline |

#### Branching strategy

| Setting | Default | Description |
|---------|---------|-------------|
| `branch_format` | `"{kind}/{title}"` | Branch naming (`{kind}`, `{title}` placeholders) |
| `branch_kinds` | `"feat\|fix\|refactor\|docs\|chore\|test\|ci"` | Allowed branch kinds |
| `protected_branches` | `"(main\|master\|develop\|release\|production\|staging)"` | Branches the pipeline auto-creates a feature branch off of, and branches `/devline:git` will not push to without asking |

#### Framework overrides

| Setting | Default | Description |
|---------|---------|-------------|
| `test_framework` | auto-detect | e.g., `"vitest"`, `"jest"`, `"pytest"` |
| `frontend_framework` | auto-detect | e.g., `"react"`, `"vue"`, `"svelte"` |
| `doc_format` | auto-detect | e.g., `"markdown"`, `"asciidoc"` |
| `cloud_provider` | auto-detect | e.g., `"aws"`, `"gcp"`, `"azure"` |

#### Dependency management

| Setting | Default | Description |
|---------|---------|-------------|
| `dep_branch_strategy` | `"main"` | `"main"` = default branch, `"branch"` = per-update branch |
| `dep_auto_push` | `true` | Push after verification |
| `dep_auto_commit` | `true` | Commit after verification |
| `dep_verify_build` | `true` | Run build check |
| `dep_verify_tests` | `true` | Run test suite |

#### Design

| Setting | Default | Description |
|---------|---------|-------------|
| `sketch_model` | `sonnet` | Model for cheap exploration steps (seeds, sketches, cull) |
| `design_model` | `opus` | Model for builds, refines and critiques |
| `mockup_model` | `sonnet` | Model for mockups |
| `design_sketches` | `10` | Number of sketches per exploration |
| `design_pick` | `ask` | `ask` = you pick which sketches to build, `auto` = take the critic's top 3 |
| `design_mode` | `auto` | `auto` = M3E strict when the project uses M3E, `m3e-strict`, or `default` |

A number or "you pick" in the request always wins over these settings. Design settings are read from `.claude/devline.local.md`, then `~/.claude/devline.local.md`.

The `deps` skill (patch mode) also honors `cve_`-prefixed overrides (e.g. `cve_verify_build`), which take priority over the generic `dep_` keys. Migrate mode always runs build and test verification (not configurable).

</details>
Run `/devline:setup` to write either file, or to move settings from an older devline version into place. Every key, its default and the skill that reads it are listed in [skills/setup/references/config.md](skills/setup/references/config.md).

---

Expand Down
4 changes: 2 additions & 2 deletions agents/dependency.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,12 +15,12 @@ You are a senior software engineer specializing in dependency updates. You recei
1. **Update targets** — package name(s), ecosystem, current/affected version, target version, reason (CVE ID, migration, etc.). Migrations also include: migration-guide URLs, known breaking changes, whether a migration tool exists, and a migration checklist.
2. **Repository path** — the absolute path to work in
3. **Commit message format** — e.g. `chore(deps): CVE-XXXX-XXXXX` or `chore(deps): migrate [pkg] from v[old] to v[new]`
4. **Settings** — branch strategy, auto-commit, auto-push, and any `devline.local.md` overrides
4. **Settings** — branch strategy, auto-commit, auto-push, and any devline config overrides
5. **Mode** — whether the **Migration block** below is enabled

## Execution process

1. `cd` into the repository path; read `.claude/devline.local.md` for repo-specific settings (the launcher may have passed these — check for local overrides).
1. `cd` into the repository path; resolve the devline config for this repo (`${CLAUDE_PLUGIN_ROOT}/skills/setup/references/config.md`); the launcher may have passed settings, but the repo's own config can override them.
2. Follow the launcher's git workflow **exactly** — its checkout/pull/branch steps run before any code changes. If none specified, fall back to the kb-dependency-management defaults.
3. Detect all ecosystems present (kb-dependency-management).
4. **[Migration block: run first if enabled — see below.]**
Expand Down
2 changes: 1 addition & 1 deletion agents/implementer.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ If you find discrepancies: implement the *intent* of the spec using the *reality

### 4. Set Up Test Infrastructure
- Check for existing test framework configuration
- If `.claude/devline.local.md` exists, check for `test_framework` override
- A `test_framework` set in the devline config (`${CLAUDE_PLUGIN_ROOT}/skills/setup/references/config.md`) overrides detection
- Create test files following existing conventions
- Verify tests can be discovered and run

Expand Down
2 changes: 1 addition & 1 deletion agents/references/cloud-infra.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ Before writing infra code, detect what the project uses:
5. `cdk.json` / `Pulumi.yaml` → CDK/Pulumi
6. `.github/workflows/` → GitHub Actions
7. `Jenkinsfile`, `.gitlab-ci.yml`, `azure-pipelines.yml` → other CI/CD
8. `.claude/devline.local.md` `cloud_provider` override
8. `cloud_provider` in the devline config (`${CLAUDE_PLUGIN_ROOT}/skills/setup/references/config.md`) overrides detection

Apply TDD to infra too: write a validation script or smoke test before the change (e.g., a test that the Docker image builds and starts before writing the Dockerfile).

Expand Down
2 changes: 1 addition & 1 deletion agents/references/documentation.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ On-demand guidance for the docs-keeper: separate documentation files (README, AP

## Documentation Detection

Before writing, check what exists: `docs/`, `README.md`, `CHANGELOG.md`; doc generators (`typedoc.json`, `mkdocs.yml`, `docusaurus.config.js`, `.readthedocs.yml`, javadoc); `.claude/devline.local.md` `doc_format` override. Match the existing format, style, and structure.
Before writing, check what exists: `docs/`, `README.md`, `CHANGELOG.md`; doc generators (`typedoc.json`, `mkdocs.yml`, `docusaurus.config.js`, `.readthedocs.yml`, javadoc); `doc_format` in the devline config (`${CLAUDE_PLUGIN_ROOT}/skills/setup/references/config.md`) overrides detection. Match the existing format, style, and structure.

## Writing Standards

Expand Down
2 changes: 1 addition & 1 deletion skills/brainstorm/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ Before writing the document, evaluate whether the feature warrants splitting int

Decide how thorough the feature's tests should be — `deep` or `focused` — in this order:

1. **Config wins silently.** If `.claude/devline.local.md` sets `test_depth` to `deep` or `focused`, use it and say nothing.
1. **Config wins silently.** If the request or the devline config (`${CLAUDE_PLUGIN_ROOT}/skills/setup/references/config.md`) sets `test_depth` to `deep` or `focused`, use it and say nothing.
2. **Infer from signals.** Otherwise read the repo's existing test style AND the user's prompt:
- Repo: dense per-method unit tests on trivial code → lean `deep`; sparse, or integration/behavior-heavy → lean `focused`.
- Prompt: "production-grade", "thorough", "exhaustive" → `deep`; "quick", "prototype", "just wire it up" → `focused`.
Expand Down
9 changes: 8 additions & 1 deletion skills/deps/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,14 @@ Present a migration plan and **wait for approval** before launching any agents:

## Step 4: Read Settings (patch mode)

Check `.claude/devline.local.md` in each repo. Map CVE settings to the generic ones (prefixed wins): `cve_verify_build` → `dep_verify_build` (default `true`), `cve_verify_tests` → `dep_verify_tests` (default `true`). Git workflow is not configurable. For **migrate mode**, build + test verification is always on and cannot be disabled.
Resolve the config for each repo; lookup and precedence: `${CLAUDE_PLUGIN_ROOT}/skills/setup/references/config.md` (the repo layer is that repo's own `.claude/devline.md`). Git workflow is not configurable here.

### Defaults

- `cve_verify_build`: the value of `dep_verify_build` (default `true`); the prefixed key wins.
- `cve_verify_tests`: the value of `dep_verify_tests` (default `true`); the prefixed key wins.

For **migrate mode**, build + test verification is always on and cannot be disabled.

## Step 5: Launch dependency agents

Expand Down
6 changes: 3 additions & 3 deletions skills/design/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,13 +25,13 @@ python3 -I <base>/scripts/gallery.py <workdir> <items-subdir> <captures-subdir>
```
capture needs playwright-core in `~/.cache/devline/capture`. If it's missing, ask before installing (about 150 MB): `npm i --prefix ~/.cache/devline/capture playwright-core && node ~/.cache/devline/capture/node_modules/playwright-core/cli.js install chromium`. Without it, the critic judges from the HTML only and the report says so.

## Settings
Read `.claude/devline.local.md` (repo), then `~/.claude/devline.local.md` (user); the repo wins. All keys optional:
## Defaults
The devline config files override these; lookup and precedence: `${CLAUDE_PLUGIN_ROOT}/skills/setup/references/config.md`.
- `sketch_model` (default `sonnet`) for seeds, sketch and cull; `design_model` (default `opus`) for build, refine and critique; `mockup_model` (default `sonnet`)
- `design_sketches` (default 10), `design_pick`: `ask` (default) | `auto`
- `design_mode`: `auto` (default) | `m3e-strict` | `default`

**Precedence for counts and who picks:** the user's request (a number, "you pick", "just build three") > settings > ask when it isn't obvious. Never override an explicit instruction in the request.
**Precedence for counts and who picks:** the user's request (a number, "you pick", "just build three") > config > ask when it isn't obvious. Never override an explicit instruction in the request.

## Inputs (both modes)
- **Facts**: the real content (files, a facts file, the project itself). Never invent content.
Expand Down
2 changes: 2 additions & 0 deletions skills/design/tests/test_structure.py
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,8 @@ def test_named_paths_exist(self):
for doc in (SKILL, AGENT):
# kb-m3e ships separately; strict mode checks for it at run time.
text = read(doc).replace("kb-m3e/references", "")
# Plugin-root paths point outside this skill (e.g. the shared config reference).
text = re.sub(r"\$\{CLAUDE_PLUGIN_ROOT\}/\S+", "", text)
paths = set(PATH.findall(text))
self.assertTrue(paths, f"{doc.name}: no references/ or scripts/ paths found")
for p in paths:
Expand Down
9 changes: 5 additions & 4 deletions skills/devline/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ That's it. Do NOT read source files to understand errors. Do NOT run a second bu

## Change Classification (before Stage 1)

Read `fast_lane` from `.claude/devline.local.md` (default `auto`; values `auto|always|off`). Classify the request before starting Stage 1:
Resolve `fast_lane` from the config (see Defaults). Classify the request before starting Stage 1:

- **Bug/fix/debug** (bug fix, compile error, test failure, stack trace — not a new feature): skip Stages 1-2 (brainstorm/plan), run the build once, then launch a **debugger** agent, followed by a **reviewer**.
- **SMALL → Fast Lane.** Classify SMALL when ANY of: the user invoked `/devline:quick`, OR `fast_lane: always`, OR it's a bugfix/typo/small tweak, OR the change is ≲1 file / ≲30 lines with **no new component, no schema/migration, no new endpoint, and no new UI surface**. Ambiguous? Ask ONE AskUserQuestion — "This looks small — fast lane or full pipeline?" (default: fast lane). Skip the question when `fast_lane: always` (force fast) or `fast_lane: off` (never fast — run the full pipeline).
Expand Down Expand Up @@ -64,17 +64,18 @@ Mark each `in_progress` when starting and `completed` when done. **Do not render

Persist all mutable state to files — conversation context is disposable summaries only. During Stage 3, state files (`.devline/state.md`, `.devline/deferred-findings.md`, `.devline/fix-task-*.md`) are written per `references/implementation-protocol.md`. On resume-after-crash (or any uncertain pipeline state), read `references/recovery.md` for the state-file schemas and the recovery protocol.

## Configuration
## Defaults

The devline config files override these; lookup and precedence: `${CLAUDE_PLUGIN_ROOT}/skills/setup/references/config.md`.

Read `.claude/devline.local.md` (if it exists):
- **`auto_approve_brainstorm`** (default: `false`) — Skip brainstorm approval gate
- **`auto_approve_plan`** (default: `false`) — Skip plan approval gate
- **`fast_lane`** (default: `auto`; `auto|always|off`) — Controls fast-lane detection for small changes (see Change Classification above)

## Pipeline Stages

### Stage 0: Branch Setup (Automatic)
1. Read branching settings from `.claude/devline.local.md` (`branch_format`, `branch_kinds`, `protected_branches`)
1. Resolve the branching settings (`branch_format`, `branch_kinds`, `protected_branches`) from the config, falling back to the git skill's Defaults
2. **Active pipeline detection:** If `.devline/state.md` exists, this is a resume scenario (new conversation or post-compaction). Run the recovery protocol (`references/recovery.md`) and ask the user whether to resume or start fresh. If resuming, skip to the recovered stage.
3. If on a protected branch (default: main, master, develop, release, production, staging): create a branch using `branch_format` (default: `{kind}/{title}`). The `{kind}` must be one of `branch_kinds` (default: feat, fix, refactor, docs, chore, test, ci).
4. Create `.devline/`; if git does not already ignore it, add it to `.git/info/exclude` (local, no tracked-file change)
Expand Down
4 changes: 2 additions & 2 deletions skills/git/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ You handle commits, pushes and pull requests during or at the end of a devline p

## Defaults

`.claude/devline.local.md` overrides any value here; a later config layer may replace this section. The rest of this skill refers to these values instead of repeating them.
The devline config files override any value here; lookup and precedence: `${CLAUDE_PLUGIN_ROOT}/skills/setup/references/config.md`. Git policy written as prose in those files (squash merges, a PR for every change, commit size) wins over these defaults too. The rest of this skill refers to these values instead of repeating them.

- **Protected branches** (`protected_branches`): main, master, develop, release, production, staging.
- **Branch names**: `branch_format` `{kind}/{title}`; `branch_kinds` feat, fix, refactor, docs, chore, test, ci.
Expand All @@ -34,7 +34,7 @@ Each mode includes the one before it. Free text maps to the nearest mode ("commi

## Branch guard (all modes)

Read `protected_branches`, `branch_format` and `branch_kinds` from `.claude/devline.local.md`, falling back to the Defaults. If the current branch is protected:
Resolve `protected_branches`, `branch_format` and `branch_kinds` from the config, falling back to the Defaults. If the current branch is protected:

- `commit`: ask whether to branch off first. Offer a name built from `branch_format`, with `{kind}` taken from the commit type when it is one of `branch_kinds` (otherwise `chore`) and `{title}` a short kebab-case summary.
- `push` / `pr`: offer to branch off as above. If the user declines, push only after an explicit yes to pushing to that branch.
Expand Down
4 changes: 2 additions & 2 deletions skills/kb-dependency-management/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -114,9 +114,9 @@ Check for custom test commands in `package.json` scripts, `Makefile`, or CI conf
- If the failure is a straightforward compatibility issue (import path changed, method renamed, type signature updated), fix it as part of the update
- If the failure is complex or touches significant application logic, do not commit — report the issue with details (error output, affected files) and let the user decide

## Settings
## Defaults

Read `.claude/devline.local.md` YAML frontmatter in each repo for these settings. All are optional — defaults shown:
Resolve these from the devline config in each repo; lookup and precedence: `${CLAUDE_PLUGIN_ROOT}/skills/setup/references/config.md`.

| Setting | Default | Description |
|---------|---------|-------------|
Expand Down
Loading
Loading