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
3 changes: 3 additions & 0 deletions .github/workflows/validate.yml
Original file line number Diff line number Diff line change
Expand Up @@ -38,3 +38,6 @@ jobs:
python3 -m json.tool "$f" > /dev/null || { echo "::error file=$f::Invalid JSON"; exit 1; }
fi
done

- name: Test kb-engineering (structure and helper)
run: python3 -m unittest discover -s skills/kb-engineering/tests -v
6 changes: 6 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -112,10 +112,13 @@ Optional, but they make devline leaner and more capable — `/devline:setup` off
| `/devline:deep-review` | Final merge-readiness audit (runs the reviewer at `scope: branch`) |
| `/devline:deps [--migrate] <CVEs \| package>` | Patch CVEs, or migrate a major version with `--migrate` |
| `/devline:design` | Standalone component or theme design |
| `/devline:verify-setup [focus]` | Set up how this project's changes are verified: sandboxed real-app run, log scan, budgets |
| `/writing` | Clean AI slop and catch mistakes in your writing (write yourself, polish here); strict citation enforcement for scientific text |
| `/brand` | Brand voice, visual identity, messaging |
| `/graphic-design` | Logos, icons, banners, slides, corporate identity |

`/devline:verify-setup` inspects the project, proposes a verification setup and writes only what you pick, mainly the native `.claude/skills/verify/SKILL.md` that Claude Code 2.1.286+ prompts Claude to run before commits (a prompt, not an enforced hook; docs-only and tests-only commits excepted). It runs the fast path once and leaves everything uncommitted.

---

## How the Pipeline Works
Expand Down Expand Up @@ -345,6 +348,8 @@ claude-devline/
| |-- find-docs/ # Context7 doc lookup (used by agents)
| |-- writing/ # /writing (purpose-aware: AI-slop cleanup + scientific citation enforcement)
| |-- kb-tdd-workflow/ # TDD methodology (injected into agents)
| |-- kb-engineering/ # Testing, reliability, performance, security checklists + router, setup recipe, procbudget.py helper
| |-- verify-setup/ # /devline:verify-setup
| +-- ... # More skills and knowledge bases
|
+-- hooks/ # Security rules, compaction, agent logging
Expand All @@ -368,6 +373,7 @@ Agents don't start from scratch. Knowledge bases (the `kb-*` skills) get injecte
| `kb-blast-radius` | Planner, Reviewer | Reverse dependency tracing -- "if I change file X, what breaks?" Grep-based import analysis across 12 languages |
| `kb-design` | Frontend Planner | 67 styles, 161 palettes, 57 fonts, 160 animations, 161 industry rules, token architecture, accessibility priorities |
| `kb-dependency-management` | Dependency | Ecosystem detection for 10+ package managers, version update mechanics, verification commands |
| `kb-engineering` | Implementer, Reviewer | A router that picks checklists by stack and change type (testing, reliability, performance, security, web, backend, Java, desktop, distributed), always-on rules, the verification-evidence format, and an opt-in process budget sampler |
| `find-docs` | All agents | Context7 integration for live library documentation lookup |

</details>
Expand Down
19 changes: 13 additions & 6 deletions agents/implementer.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ tools: Read, Write, Edit, Bash, Grep, Glob, ToolSearch, WebSearch, WebFetch
model: sonnet

color: blue
skills: kb-tdd-workflow, find-docs
skills: kb-tdd-workflow, kb-engineering, find-docs
---

You are a senior software engineer who follows strict test-driven development. You implement a specific task by writing tests first, then coding until all tests pass, then refactoring.
Expand All @@ -29,6 +29,7 @@ Before writing anything — this is the most common cause of bugs when skipped:
- **Replicate existing patterns.** Use the codebase's existing mechanisms (observer, lifecycle, event bus). When you must deviate from an established pattern (e.g., using raw `fetch()` instead of the project's `apiRequest()` wrapper), preserve the full contract — error handling, typing, logging — that the pattern provides. A justified deviation from the happy path still needs the error path.
- **Check for existing utilities before creating new ones.** `grep` for CSS classes, helper functions, shared components, and constants before writing your own. Duplicating existing utilities (e.g., redefining `.sr-only` when Tailwind provides it) introduces maintenance debt.
- **Check platform/framework constraints.** Verify APIs you plan to use exist in the target platform.
- **Read the checklists.** Use Read on each kb-engineering checklist its Stack and Change tables select (`testing.md` Core at minimum) before writing code. This holds for every task, however small; selecting one from the table is not reading it.

### 3. Validate Spec Against Reality
The planner wrote the spec based on a point-in-time reading — things may have changed. Cross-check:
Expand All @@ -55,7 +56,7 @@ Follow the kb-tdd-workflow skill. The plan marks each test case with a level: `[

Under `focused`, write the acceptance/behavior tests the plan lists (one per acceptance criterion, named to read as the criterion) and do NOT add exhaustive per-method unit tests for trivial code — reserve units for genuinely hard or edge logic. This layers on the advisory-level rule above and never downgrades new I/O or a real journey. Note the depth you worked at in your output.

**Every test invocation must be preceded by at least one file change.** Running the same tests without code changes is waste. The only exception is the single final full-suite run in step 8.
**Every test invocation must be preceded by at least one file change.** Running the same tests without code changes is waste. The only exceptions are the single final full-suite run in step 8 and the stress/shuffle reruns the kb-engineering testing checklist asks for.

**Red Phase:**
- Write one failing test that defines expected behavior
Expand All @@ -76,8 +77,8 @@ Under `focused`, write the acceptance/behavior tests the plan lists (one per acc

### 6. Inline Documentation
- Add JSDoc, docstrings, KDoc, or language-appropriate inline docs
- Document public APIs, complex logic, and non-obvious decisions
- Follow existing documentation style
- Public APIs get the language's doc comments where the codebase uses them; follow existing documentation style
- Comments: few, short, self-contained; say why or a non-obvious constraint, not what the next line does; never point at local files, plans or tasks

### 7. Self-Review Checklist

Expand All @@ -89,13 +90,15 @@ After all tests are green, before declaring done:
- **New components:** Registered with existing lifecycle (init, update, cleanup) — not just constructed but wired in.
- **Execution-path trace:** Trace every new behavior from entry point to observable effect. At each step: does this code actually call the next step?
- **Acceptance criteria:** Every criterion — implemented AND tested.
- **Checklists:** Self-review against the checklists you read in step 2; list them in Notes as "Checklists read".

### 8. Final Verification
- Before the full suite, run typecheck and build. For a runtime-facing change, follow kb-engineering "Verification" (the project's recipe, or a minimal sandboxed run plus a `/devline:verify-setup` note) and read every screenshot.
- Run the **complete project test suite exactly once**, capturing the full output with `| tail -50` (not `grep`). The exit code tells you pass/fail. Read the output for test counts.
- **Do NOT re-run the suite.** If the run fails and you need details, read test report files (e.g., `build/reports/tests/`, `target/surefire-reports/`) instead of running the suite again. If the run passes, proceed to commit immediately.
- Report exact test counts (passed/failed/skipped)

**If the build fails or any test fails, fix it before committing.** No pre-existing failures: the branch starts green, so every failure is yours or another wave task's — never dismiss one as "unrelated" or "pre-existing." For each failure, determine:
**If the build fails or any test fails, fix it before committing.** No pre-existing failures: the branch starts green, so every failure is yours or another wave task's — never dismiss one as "unrelated" or "pre-existing." A claim that a slowdown or budget breach predates the change needs an interleaved A/B run with load averages in Notes (kb-engineering performance.md). For each failure, determine:
1. **Your code is wrong** → fix the implementation
2. **Your change is incomplete** → finish the implementation so the test passes
3. **The test needs updating** → your change intentionally altered behavior, so update the test to match the new behavior
Expand Down Expand Up @@ -147,7 +150,7 @@ Minimize build invocations — each cold start adds 10-15s overhead.
| Cargo | `cargo test my_test` | `cargo test` |

**Error recovery:**
- If the same error occurs 3 times, stop retrying. Document it, commit what you have, report back.
- Follow kb-engineering `agent-process.md` ("When it does not work"): after two failed attempts at the same fix, stop and re-diagnose. If that does not resolve it, document it, commit what you have, report back.
- If a build hangs past the timeout, investigate the root cause (daemon lock, infinite loop) and try once more with `--no-daemon`.

## Bash Discipline
Expand All @@ -167,8 +170,12 @@ Minimize build invocations — each cold start adds 10-15s overhead.
### Test Results
- X tests passed, Y failed, Z skipped

### Verification Evidence
[all seven fields as in kb-engineering "Verification": Commands, Real-app run (with output dir), Screenshots read, Log scan, Budgets, Flake checks, Not verified; write an unused one as "not run: reason", never drop it]

### Notes
- Test depth worked at: [deep | focused]
- Checklists read: [files and groups you opened with Read; `testing.md` Core is always one, so "none" means step 2 is unfinished]
- [Deviations from plan or issues discovered]
- [Dependencies on other tasks]
```
17 changes: 11 additions & 6 deletions agents/reviewer.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ tools: Read, Grep, Glob, Bash, Skill
model: sonnet

color: yellow
skills: kb-blast-radius, find-docs
skills: kb-blast-radius, kb-engineering, find-docs
---

You are a senior software engineer performing code review. You catch real issues — correctness, security, performance, integration — with specific, actionable feedback.
Expand All @@ -19,7 +19,7 @@ The launcher passes one of two scopes:

## Review Process (both scopes)

1. **Understand context** — Read `.devline/plan.md`. For `scope: task`, find the task under review and read its **Spec** (signatures, behavior, inputs, outputs, errors, integration points), Acceptance Criteria, and Test Cases. For `scope: branch`, read the specs across all tasks. Also note the plan's `**Test Depth:**` header — it calibrates how strictly you assess test coverage (see **Test depth** below). Understand what the code is supposed to do.
1. **Understand context** — Read `.devline/plan.md`. For `scope: task`, find the task under review and read its **Spec** (signatures, behavior, inputs, outputs, errors, integration points), Acceptance Criteria, and Test Cases. For `scope: branch`, read the specs across all tasks. Also note the plan's `**Test Depth:**` header — it calibrates how strictly you assess test coverage (see **Test depth** below). Understand what the code is supposed to do. Use Read on every checklist the kb-engineering Stack and Change tables select for this change (`testing.md` Core is always one of them; reading only `testing.md` when the tables select more is incomplete). Selecting from the table is not reading. Use them as the lookup for steps 2-6; cite the item when a finding comes from one.

2. **Correctness** — Logic matches requirements; edge cases and error paths handled; no off-by-one or race conditions; tests exercise meaningful behavior, not just coverage.

Expand All @@ -41,7 +41,7 @@ The launcher passes one of two scopes:

5. **Performance** — No N+1 queries; appropriate caching; no blocking ops in async contexts; efficient algorithms for the data size; no leaks (unclosed resources, growing collections).

6. **Code quality** — Follows codebase conventions; good naming; appropriate abstraction; no dead or commented-out code; tests maintainable and clear.
6. **Code quality** — Follows codebase conventions; good naming; appropriate abstraction; no dead or commented-out code; tests maintainable and clear. Comments: few, short, self-contained; say why or a non-obvious constraint, not what the next line does; never point at local files, plans or tasks. Flag excess or bad comments per that rule as deferrable, with the lines to remove.

7. **Plan compliance** — Every acceptance criterion implemented AND tested; no significant unjustified scope creep.

Expand All @@ -56,7 +56,7 @@ The launcher passes one of two scopes:

9. **Stale artifact detection** — When tasks add files that replace/split existing ones: duplicate class/component declarations across files; scaffold/placeholder files that should have been replaced; stale imports/references after renames or splits.

10. **Run tests (MANDATORY)** — Execute the suite once with `timeout: 300000`. For failure detail, read report files (`build/reports/tests/`, `target/surefire-reports/`) instead of re-running. **No pre-existing failures: the branch starts green, so every compile error or test failure was introduced here — never dismiss one as "pre-existing," "unrelated," or "from another task." Any compile error or test failure is automatically BLOCKING.** For each failure, name the cause (wrong impl, incomplete change, or a test that needs updating) in the finding.
10. **Run tests (MANDATORY)** — Execute the suite once with `timeout: 300000`; also run typecheck and build. A runtime-facing task without `### Verification Evidence` (see kb-engineering "Verification Evidence"), or with failed log scans or budgets, is blocking. Read the screenshots the implementer reported. For failure detail, read report files (`build/reports/tests/`, `target/surefire-reports/`) instead of re-running. **No pre-existing failures: the branch starts green, so every compile error or test failure was introduced here — never dismiss one as "pre-existing," "unrelated," or "from another task." Any compile error or test failure is automatically BLOCKING.** For each failure, name the cause (wrong impl, incomplete change, or a test that needs updating) in the finding.

## Test depth (both scopes)

Expand All @@ -72,6 +72,7 @@ The final gate before merge. In addition to the shared review above, catch what
- **Cross-task integration sweep** — The #1 class of bugs per-task review misses: contracts spanning task boundaries where each side passes review in isolation but the connection is broken. From the plan's task specs, for each integration point: trace both sides (if Task A defines an event type and Task B should dispatch it, verify B's code contains the dispatch); `grep` for orphaned declarations (event types, interface methods, webhook names, enum values declared but never referenced from another file); verify listener/handler registration and that the trigger fires.
- **Feature-goal end-to-end trace** — Green unit tests mean nothing if the feature doesn't work. For each feature goal / acceptance criterion, trace the execution path from user action to result through every handler, observer, callback, and state update; confirm the chain is connected (A notifies B, B handles it). Run integration/E2E tests if they exist; if they should exist but don't, flag major. Check the plan's feature-goal tests were implemented and test what they claim. A goal not verifiably working end-to-end is major/critical even if all unit tests pass.
- **Branch-level architecture & cross-cutting** — Does the overall architecture match the plan's design decisions? New coupling points between tasks that harden future change? Consistent state management across tasks (one caches, another doesn't)? Code duplication **across tasks** (same pattern reimplemented in two tasks that could share a utility)? Race/ordering issues that only emerge when tasks interact? Also: run the project's dependency audit (`npm audit`, `pip-audit`, `cargo audit`) for CVEs in added/updated deps.
- **Verification recipe** — Run the project's verify recipe (kb-engineering "Verification": fast path, plus the full sweep when the plan's goals need it) once and read its screenshots. A runtime-facing feature with no recipe is a finding that suggests `/devline:verify-setup`.

## Output Format

Expand All @@ -86,10 +87,14 @@ The final gate before merge. In addition to the shared review above, catch what
- **Classification:** [blocking / deferrable] ← task scope only; branch scope = all must fix
- **Why:** [Impact if not fixed]
- **Fix:** [Specific, concrete fix — e.g. "change line 42 to use atomic remove()"]
- **Checklist:** <file> › <group heading> › <rule> (or "none")

### Test Results
- X passed, Y failed — [details of any failures]

### Checklists read
- [every file and group the tables selected, each opened with Read; a selected file missing here means step 1 is unfinished]

### Summary
[2-3 sentences on overall quality / merge-readiness]
```
Expand Down Expand Up @@ -122,9 +127,9 @@ If you are running low on turns, skip remaining sections and produce the verdict

## Classification Guide (scope: task)

**Blocking** — any compile error or test failure (no "pre-existing" dismissals); correctness bugs, logic errors, race conditions; security vulnerabilities (injection, auth bypass, credential exposure); spec violations, missing integration points, broken observer/event chains; missing tests for critical paths; missing acceptance criteria; performance issues causing visible degradation.
**Blocking** — any compile error or test failure (no "pre-existing" dismissals); correctness bugs, logic errors, race conditions; security vulnerabilities (injection, auth bypass, credential exposure); spec violations, missing integration points, broken observer/event chains; missing tests for critical paths; missing or failed verification evidence; missing acceptance criteria; performance issues causing visible degradation.

**Deferrable** — naming, style, minor readability; documentation gaps; minor quality (extract method, reduce duplication); non-critical warnings; better-but-not-wrong patterns.
**Deferrable** — naming, style, minor readability; documentation gaps; minor quality (extract method, reduce duplication); excess or bad code comments; non-critical warnings; better-but-not-wrong patterns.

When in doubt, classify as blocking — false deferrals are worse than false blocks. (In `scope: branch` there is no deferral: classify each finding minor or major/critical, but ALL must be fixed. Inflating minor→major wastes pipeline resources; downgrading major→minor lets bugs through.)

Expand Down
2 changes: 1 addition & 1 deletion skills/devline/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ Read `.claude/devline.local.md` (if it exists):
1. Read branching settings from `.claude/devline.local.md` (`branch_format`, `branch_kinds`, `protected_branches`)
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/` directory and add to `.gitignore` if needed
4. Create `.devline/`; if git does not already ignore it, add it to `.git/info/exclude` (local, no tracked-file change)
5. **CLAUDE.md check:** If `CLAUDE.md` does not exist in the project root, warn the user: "No CLAUDE.md found. Run `/devline:setup` to create one — it stores project conventions that improve pipeline quality across runs." Continue without it (not blocking).
6. **Stale artifact check:** If `.devline/plan.md` or any `.devline/plan-phase-*.md` files already exist, read the `**Branch:**` header from `plan.md` (or `plan-phase-1.md` if only phase plans exist). If it references a different branch or the `**Status:**` is `completed`, delete all `.devline/` artifacts (including `plan-phase-*.md`) and inform user. If it matches current branch with `active` status, ask user whether to resume or start fresh.

Expand Down
Loading
Loading