diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 9563995..a356e0d 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -43,18 +43,6 @@ "homepage": "https://github.com/killallgit/killall-skills", "version": "5.4.1" }, - { - "name": "follow-the-rules", - "source": "./", - "description": "Core programming rules for all agents and users alike. The following documents contain the most important, fundamental, rules that every engineer - junior to principle - MUST follow.", - "strict": false, - "skills": [ - "./skills/follow-the-rules" - ], - "category": "workflow", - "homepage": "https://github.com/killallgit/killall-skills", - "version": "5.4.1" - }, { "name": "git-janitor", "source": "./", @@ -136,7 +124,6 @@ "./skills/architectural-review", "./skills/catch-up", "./skills/end-session", - "./skills/follow-the-rules", "./skills/git-janitor", "./skills/independent-review", "./skills/lets-finish", diff --git a/README.md b/README.md index 61d55ec..f2dca5a 100644 --- a/README.md +++ b/README.md @@ -130,7 +130,8 @@ paste into a fresh agent so it can resume. User-invoked only. hotspots (churn × size) and change-coupled files from git history; a fresh-context agent walks them for friction, judged against a fixed design vocabulary (module, interface, depth, seam, adapter, locality, leverage) and -the `follow-the-rules` lenses. It renders an HTML report of deepening +the `house-rules` lenses from +[killall-craft](https://github.com/killallgit/killall-craft). It renders an HTML report of deepening candidates with before/after Mermaid diagrams and proposed glossary terms, and prints the `bd create` commands for an epic plus one bead per candidate, which it runs only for the candidates you pick. It keeps `GLOSSARY.md`, diff --git a/skills/architectural-review/references/vocabulary.md b/skills/architectural-review/references/vocabulary.md index 6349d70..ab5a957 100644 --- a/skills/architectural-review/references/vocabulary.md +++ b/skills/architectural-review/references/vocabulary.md @@ -46,7 +46,7 @@ form, and keep strong forms inside one module. ## Friction signals -Each signal comes from `follow-the-rules`; cite it in a candidate's `rules`. +Each signal comes from the `house-rules` skill in killall-craft; cite it in a candidate's `rules`. - Understanding one concept means bouncing between many small modules. - Pure functions extracted only for tests, while bugs hide in how they're diff --git a/skills/follow-the-rules/SKILL.md b/skills/follow-the-rules/SKILL.md deleted file mode 100644 index f70d74d..0000000 --- a/skills/follow-the-rules/SKILL.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -name: follow-the-rules -description: Core programming rules for all agents and users alike. The following documents contain the most important, fundamental, rules that every engineer - junior to principle - MUST follow. ---- - -# Programming Commandments (non-negotiable) - -# **important, , MUST, , ALWAYS** follow the following rules when writing ANY code. - -## 1. If the code can be simplified, simplify it. -- We are not creating software to land rovers on the moon. Do not write code to pass this kind of review. - -## 2. If the code can be deleted, delete it. -- Git exists for a reason. There is no reason to save text that has already been saved and isn't needed. -- Follow functions, often times only a test will be calling a function which makes that code dead. Remove the function and test. - -## 3. Code should be self documenting. Do NOT add unnecessary comments that describe what the code already describes. - -Examples for each of the following languages: [python](./references/python-example.md), [golang](./references/go-example.md), [rust](./references/rust-example.md), [typescript](./references/typescript-example.md) - -## 4. Never, under any circumstances take agent information at face value. ALWAYS validate, verify, and test. When working with other agents, assume they are junior developers with zero experience or knowlege of company requirements. Double check their work. - -## 5. Code should read like prose. - -- How you name variables, functions and how you organize files and write your tests all tell a story about the purpose of the code. Constantly ask yourself, "if i were reading this for the first time, start to finish, would i understand what this is doing in a day?" -- Code can be complex, the goal is to reduce the amount of time it takes someone to understand and work with the code. Optimization is important but when it comes at the cost of understanding, think about how you're telling the story. - -# More flexible rules (but still important) - -- Program to interfaces, methods should be open for extension not for modification. -- Avoid using global, mutable variables. There are very few circumstances where this is acceptable and you must ALWAYS confirm with the user and provide a clear reason why you want to build in this way. Encapsulate! -- Favor configuration/context objects over many arguments: Use imutable data classes or objects where possible. -- Avoid passing more than 3-4 arguments to a function. This is not a hard rule but generally should be followed. -- Follow functional programming paradigms: Use pure functions, composability, and dependency injection. -- Follow TDD principles when programming. -- Do NOT, assert on logs, error message strings, or strings in general unless theres a very good reason for this. If you want to assert that an exception was raised, assert on the concrete exception type itself. If you cant do this easily that's a 'code smell' and a refactor might be warranted. -- Functions, methods should do a single thing. They should be named descriptively and you should have many of them. If it makes sense to have a single function in a single module, do that. -- When you feel like you need a "utility" this is an indication that you dont have your domains defined well enough. Of course there are execptions but consider the pattern. -- Linting and typechecking need to always be green before code both pushes to a remote and through CI pipelines. -- If a change we put in triggers a latent issue with a test, linting, or typecheck that has nothing to do with the code we were touching, we stop and fix it. The exception here is when we need to move quickly. Look for a parallel agent to fix this. -- Documentation goes stale quickly. Avoid documenting at a detal that tends toward stale. Always be looking to improve the documentation before our work. -- Separate unit tests from integration tests. Integration tests should be kept separately runnable. Tests need to follow the latest best practices for the test harness being used. Make sure your tests use DI and are functional -- Test function comments should describe the assertion and the test should follow the 3 A's of testing: Assemble, Act, Assert. diff --git a/skills/follow-the-rules/references/go-example.md b/skills/follow-the-rules/references/go-example.md deleted file mode 100644 index 3e191b5..0000000 --- a/skills/follow-the-rules/references/go-example.md +++ /dev/null @@ -1,61 +0,0 @@ -Bad test with bad comments - -```go -// monkey_builder.go - -// Package monkey is a package for building monkeys that jump on any bed -// provided as a configuration. -package monkey - -// BuildMonkey builds a monkey. It takes a string, foo, and an int, bar, and -// returns a Monkey and an error. -func BuildMonkey(foo string, bar int) (*Monkey, error) { - - // hold the count of monkies - countMonkie := 0 - ... -} - -// TestBuildMonkey1 tests the build monkey function -func TestBuildMonkey1(t *testing.T) { - m, err := BuildMonkey("safe-monkey", 9) - if err != nil && err.Error() != "bed is missing" { - t.Fatal("it broke") - } - f := TriggerFall(m) - if f.Bed() != BedSoft { - t.Fatal("bad bed") - } - // now check a tall one - m2, _ := BuildMonkey("doomed-monkey", 400) - if TriggerFall(m2).Bed() != BedHard { - t.Fatal("bad bed") - } -} -``` - -Good test with a comment that describes the assertion - -```go -func TestFallOnSoftBed(t *testing.T) { - // It falls on a soft bed when dropped from a low height - monkey := NewMonkey().WithHeight(9).WithName("safe-monkey").Build() - - fallen := TriggerFall(monkey) - - if got := fallen.Bed(); got != BedSoft { - t.Errorf("Bed() = %v, want %v", got, BedSoft) - } -} - -func TestFallWithoutBed(t *testing.T) { - // It refuses to drop a monkey when no bed is configured - monkey := NewMonkey().WithHeight(9).Build() - - _, err := TriggerFallOrErr(monkey) - - if !errors.Is(err, ErrNoBed) { - t.Errorf("err = %v, want %v", err, ErrNoBed) - } -} -``` diff --git a/skills/follow-the-rules/references/python-example.md b/skills/follow-the-rules/references/python-example.md deleted file mode 100644 index 7a9755e..0000000 --- a/skills/follow-the-rules/references/python-example.md +++ /dev/null @@ -1,30 +0,0 @@ -Bad test with bad comments - - -```python -# monkey_builder.py -""" -A module for building monkeys that jump on any bed provided as a configuration. -""" - -# This function builds a monkey and takes a string, "foo", and a int, "bar" as arguments -def build_monkey(foo: str, bar: int): - - # hold the count of monkies - count_monkie = 0 -``` - -Good test with a comment that describes the assertion - -```python -def test_fall_on_soft_bed(): - """ - It falls on a soft bed when at a low height - """ - - mock_monkey = build_monkey().set_height(9).set_name("safe-monkey").build() - - fallen_monkey = trigger_fall(mock_monkey) - - expect(fallen_monkey.get_bed()).to_be(MonkeyBeds.SOFT) -``` \ No newline at end of file diff --git a/skills/follow-the-rules/references/rust-example.md b/skills/follow-the-rules/references/rust-example.md deleted file mode 100644 index 83d631d..0000000 --- a/skills/follow-the-rules/references/rust-example.md +++ /dev/null @@ -1,50 +0,0 @@ -Bad test with bad comments - -```rust -// monkey_builder.rs -//! A module for building monkeys that jump on any bed provided as a -//! configuration. - -/// This function builds a monkey and takes a `&str`, `foo`, and a `u32`, -/// `bar`, as arguments. Returns a Result. -pub fn build_monkey(foo: &str, bar: u32) -> Result { - - // hold the count of monkies - let mut count_monkie = 0; - ... -} - -#[test] -fn test_monkey() { - let m = build_monkey("safe-monkey", 9).unwrap(); - let f = trigger_fall(m); - assert!(f.bed() == Bed::Soft, "bad bed"); - // now check the error case - let e = build_monkey("bedless-monkey", 9).unwrap_err(); - assert_eq!(e.to_string(), "no bed configured"); -} -``` - -Good test with a comment that describes the assertion - -```rust -#[test] -fn falls_on_soft_bed() { - // It falls on a soft bed when dropped from a low height - let monkey = Monkey::builder().height(9).name("safe-monkey").build(); - - let fallen = trigger_fall(monkey); - - assert_eq!(fallen.bed(), Bed::Soft); -} - -#[test] -fn refuses_to_fall_without_a_bed() { - // It refuses to drop a monkey when no bed is configured - let monkey = Monkey::builder().height(9).build(); - - let err = trigger_fall(monkey).unwrap_err(); - - assert!(matches!(err, MonkeyError::NoBed)); -} -``` diff --git a/skills/follow-the-rules/references/typescript-example.md b/skills/follow-the-rules/references/typescript-example.md deleted file mode 100644 index 4acbf51..0000000 --- a/skills/follow-the-rules/references/typescript-example.md +++ /dev/null @@ -1,53 +0,0 @@ -Bad test with bad comments - -```typescript -// monkeyBuilder.ts -/** - * A module for building monkeys that jump on any bed provided as a - * configuration. - */ - -/** - * This function builds a monkey. - * @param foo - a string - * @param bar - a number - * @returns a Monkey - */ -export function buildMonkey(foo: string, bar: number): Monkey { - - // hold the count of monkies - let countMonkie = 0; - ... -} - -describe("buildMonkey", () => { - it("works", () => { - const m = buildMonkey("safe-monkey", 9); - expect(triggerFall(m).bed).toBe(Bed.Soft); - // now check the error case - try { - triggerFall(buildMonkey("bedless-monkey", 9)); - } catch (e: any) { - expect(e.message).toBe("no bed configured"); - } - }); -}); -``` - -Good test with a comment that describes the assertion - -```typescript -it("falls on a soft bed when dropped from a low height", () => { - const monkey = monkeyBuilder().height(9).name("safe-monkey").build(); - - const fallen = triggerFall(monkey); - - expect(fallen.bed).toBe(Bed.Soft); -}); - -it("refuses to drop a monkey when no bed is configured", () => { - const monkey = monkeyBuilder().height(9).build(); - - expect(() => triggerFall(monkey)).toThrow(NoBedError); -}); -```