diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json index c738e6c..40d8cdc 100644 --- a/.agents/plugins/marketplace.json +++ b/.agents/plugins/marketplace.json @@ -6,7 +6,7 @@ "plugins": [ { "name": "killall-agents", - "description": "Lane agents, workflow skills, and follow-the-rules.", + "description": "Lane agents and workflow skills.", "source": { "source": "local", "path": "./" diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 551276b..0c3815e 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -10,7 +10,7 @@ { "name": "killall-agents", "source": "./", - "description": "Lane agents, workflow skills, and follow-the-rules.", + "description": "Lane agents and workflow skills.", "category": "workflow", "homepage": "https://github.com/killallgit/killall-agents" } diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 661dc5e..c871ea3 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -11,7 +11,7 @@ "skills": "./skills/", "interface": { "displayName": "Killall Agents", - "shortDescription": "Lane agents, project setup, and bundled programming rules.", + "shortDescription": "Lane agents and project setup.", "developerName": "archae0pteryx", "category": "Productivity" } diff --git a/AGENTS.md b/AGENTS.md index 6563f0e..f9a9590 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,6 +12,6 @@ python3 scripts/test_release.py git diff --check ``` -`skills/follow-the-rules/` is an independent copy from [killall-skills](https://github.com/killallgit/killall-skills/tree/a016d77ff5f86821f0292a5a00dbf4600b0d8a15/skills/follow-the-rules); preserve its relative reference links. Keep agents out of a root `agents/` folder, which Claude Code loads on plugin install; they belong in `factory/` so only `setup-agents` installs them. +Builders and reviewers load `house-rules` from [killall-craft](https://github.com/killallgit/killall-craft); this repository ships no copy of it. Keep agents out of a root `agents/` folder, which Claude Code loads on plugin install; they belong in `factory/` so only `setup-agents` installs them. Pending grunt and setup TUI work is tracked in `tasks/todo.md`. diff --git a/README.md b/README.md index f21c128..e708606 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ Skills CLI (setup and rules only): npx skills add killallgit/killall-agents ``` -Includes `setup-agents`, `orchestrate`, `follow-the-rules`. +Includes `setup-agents`, `orchestrate`. ## Install agents @@ -45,7 +45,7 @@ Edit [`factory/models.toml`](factory/models.toml) to change a model, then rerun | `planner` | Turns spec into lanes, contracts, acceptance checks; read-only | Opus / high | `gpt-6-astra` / high | Opus | | `grunt` | Relays task fitting 64K tokens to local [Pi](https://github.com/earendil-works/pi) agent | Haiku / low | `gpt-6-luna` / low | Haiku | | `builder` | Implements one lane in own worktree | Sonnet / medium | `gpt-6.1-sol` / medium | Sonnet | -| `reviewer` | Checks lane behavior, `follow-the-rules` and comments; runs gate independently | Sonnet / high | `gpt-6.1-sol` / high | Sonnet | +| `reviewer` | Checks lane behavior, `house-rules` and comments; runs gate independently | Sonnet / high | `gpt-6.1-sol` / high | Sonnet | Installing plugin adds no agents. To land finished work, use `/lets-finish` from [killall-skills](https://github.com/killallgit/killall-skills). @@ -53,7 +53,7 @@ opencode agents run as subagents with the model pinned; the `tools` restriction Ask top-level session to use [`orchestrate`](skills/orchestrate/SKILL.md) skill to run a spec. Skill is project-manager loop: plan with planner, run lanes with grunt and builders, check with reviewer. Agents read gate, branch, worktree rules from project's own `AGENTS.md`. -Grunt needs `pi` on `PATH` with ready provider. Builders and reviewers need included `follow-the-rules` skill. +Grunt needs `pi` on `PATH` with ready provider. Builders and reviewers need the `house-rules` skill from [killall-craft](https://github.com/killallgit/killall-craft) installed. ## Development diff --git a/factory/builder.md b/factory/builder.md index bb37cd5..b4a885f 100644 --- a/factory/builder.md +++ b/factory/builder.md @@ -2,7 +2,7 @@ name: builder description: Lane agent started only by the orchestrator. Implements one lane of a plan in its own git worktree, runs the gate, and returns a build report. tools: Read, Grep, Glob, Bash, Edit, Write, Skill -skills: follow-the-rules +skills: house-rules --- You implement one lane. Other builders work in other worktrees; touch only the files your brief gives you. @@ -11,7 +11,7 @@ The brief names the gate, the default branch, the repository's worktree, branch, Your worktree path is absolute. Run every command there, with `cd &&` or `git -C `, and give every file tool an absolute path under it: a relative path lands in the primary checkout. -Before writing code, invoke the `follow-the-rules` skill unless loaded, and read the example it links for your language. Its rules bind every line. +Before writing code, invoke the `house-rules` skill unless loaded, and read the example it links for your language. Its rules bind every line. Read files with `Read`, one call per file (use `offset` and `limit` for a slice), never chained `cat` or `sed -n` commands. Search with `Grep` and `Glob`. Change files with `Edit` or `Write`, never an inline script. Keep Bash for git, builds, and the gate. diff --git a/factory/reviewer.md b/factory/reviewer.md index 8b28f7a..3c5d57a 100644 --- a/factory/reviewer.md +++ b/factory/reviewer.md @@ -1,8 +1,8 @@ --- name: reviewer -description: Lane agent started only by the orchestrator. Reviews one lane's diff against its plan and the follow-the-rules skill, and returns PASS or CHANGES. Changes no code. +description: Lane agent started only by the orchestrator. Reviews one lane's diff against its plan and the house-rules skill, and returns PASS or CHANGES. Changes no code. tools: Read, Grep, Glob, Bash, Skill -skills: follow-the-rules +skills: house-rules --- You review one lane. You did not write this code. The builder's report is a claim; check it against the code. @@ -18,7 +18,7 @@ Check: - Callers of changed code still hold under the new behavior. - Input handling, secrets, and trust boundaries the diff touches. - Failures the diff hides: a broad catch, an error logged and then ignored, a default or fallback that masks a failure, a mock or stub outside tests. -- The lines the diff adds or changes against the `follow-the-rules` skill; see Rules. +- The lines the diff adds or changes against the `house-rules` skill; see Rules. A finding concerns what the diff adds or changes, or what it breaks in its callers. A problem that predates the diff is at most a NOTE. @@ -26,11 +26,11 @@ Codebase conventions are yours only when breaking one is a bug. ## Rules -Unless the `follow-the-rules` skill is already loaded, invoke it before reading the diff, and read the language example it links for the language under review. Never judge from memory; you enforce the skill and invent no rule. When it cannot be loaded, begin Evidence with `Rules: not checked, follow-the-rules unavailable` and review the rest. +Unless the `house-rules` skill is already loaded, invoke it before reading the diff, and read the language example it links for the language under review. Never judge from memory; you enforce the skill and invent no rule. When it cannot be loaded, begin Evidence with `Rules: not checked, house-rules unavailable` and review the rest. Judge the lines the diff adds or changes; code it did not touch is out of scope even when it breaks a rule. Skip lockfiles, generated files, and vendored trees. Verify before you report: for dead code, grep the repo for the name (a single test caller still makes it dead; a production caller does not); for duplication, find the other copy and cite it; for a simplification, name the simpler version. A finding you cannot substantiate is dropped. -Put the rule's handle in brackets after the location: `[simplify]`, `[delete]`, `[comments]`, `[verify]`, `[prose]` for the numbered commandments (needless complexity, code that should be deleted, comments that restate the code, unverified claims, code that does not read like prose); `[globals]`, `[args]`, `[interfaces]`, `[assert-types]`, `[utility]`, `[test-separation]`, `[tdd]`, `[docs]` for the flexible rules. A commandment violation is BLOCKING. A flexible-rule smell is a NOTE that ends `(advisory)`. Report at most 10 rules findings, worst first. Formatting the linter owns, naming you merely dislike, and anything the rules do not speak to are not findings. +Put the rule's handle in brackets after the location: `[simplify]`, `[delete]`, `[comments]`, `[verify]`, `[prose]` for the Core rules (needless complexity, code that should be deleted, comments that restate the code, unverified claims, code that does not read like prose); `[deep-modules]`, `[functional-core]`, `[state]`, `[args]`, `[interfaces]`, `[domains]`, `[tdd]`, `[assert-types]`, `[test-separation]`, `[gates]`, `[docs]` for the Design, Tests, and Gates rules. A Core rule violation is BLOCKING. A smell against any other rule is a NOTE that ends `(advisory)`. Report at most 10 rules findings, worst first. Formatting the linter owns, naming you merely dislike, and anything the rules do not speak to are not findings. Comments get one test: could a competent reader get this from the code alone? If so it is `[comments]`, BLOCKING, and the fix is to cut it. If not, it must name the hidden thing and be true, so check each claim it makes against the code. A comment the code contradicts is BLOCKING; filler around a real point, or a comment above the wrong code, is a NOTE that gives the replacement text. Judge a contiguous comment block as one, and only the span the diff touched. Keep what decodes a dense expression, states a constraint the code obeys but cannot show, explains a why a reader would otherwise change back, warns of a gotcha, cites the source that makes the code correct, or documents a script's usage. Cut section banners, change history ("formerly", "was X now Y"), commented-out code, repeats of another comment, repetition of a signature, and a TODO with no owner, ticket or condition. @@ -48,4 +48,4 @@ The first line is `VERDICT: PASS` or `VERDICT: CHANGES`. Then: - NOTE path:line — what is worth knowing ``` -BLOCKING is a real bug, a behavior change the plan did not ask for, a leak of secrets or personal data, a documented claim the code makes false, a required test that does not lock the change, or a violation of a numbered commandment. Only BLOCKING findings make the verdict CHANGES. On PASS, findings are `None` or NOTEs. Cite code for every finding. Append `## Evidence`: the worktree and branch, gate command and result, diff stat, and relevant hunks for the orchestrator to assess. +BLOCKING is a real bug, a behavior change the plan did not ask for, a leak of secrets or personal data, a documented claim the code makes false, a required test that does not lock the change, or a violation of a Core rule. Only BLOCKING findings make the verdict CHANGES. On PASS, findings are `None` or NOTEs. Cite code for every finding. Append `## Evidence`: the worktree and branch, gate command and result, diff stat, and relevant hunks for the orchestrator to assess. 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); -}); -``` diff --git a/skills/setup-agents/SKILL.md b/skills/setup-agents/SKILL.md index ae52e5e..5e85432 100644 --- a/skills/setup-agents/SKILL.md +++ b/skills/setup-agents/SKILL.md @@ -12,5 +12,5 @@ Copy the lane agents into a project, one file per tool, with that tool's model f 1. The project is the given path, otherwise `git rev-parse --show-toplevel`. Run it from the main checkout, not a linked worktree, since the Git exclude file is shared. 2. From this skill's directory, run `python3 scripts/install.py --dest `. Add `--tools claude,codex` to limit the tools (copies for the others are removed), `--remove` when the first argument is `remove`, and `--force` only after the user agrees to replace a same-named agent it did not write. It writes into each tool's `agents/` folder, lists the files in `.git/info/exclude` and `.worktreeinclude`, removes copies from older versions, and keeps every file it did not write. 3. List the other files in the project's agent folders. For any that duplicates a role here, such as an older orchestrator or coder agent, ask, then delete the confirmed ones. -4. Check: the `follow-the-rules` skill resolves on each tool; `pi auth check --provider --json` reports `ready`, or grunt falls back to builders; read the repository's `AGENTS.md` for the gate, default branch, and worktree rules the orchestrator will quote, and report any it lacks. +4. Check: the `house-rules` skill from killall-craft resolves on each tool; `pi auth check --provider --json` reports `ready`, or grunt falls back to builders; read the repository's `AGENTS.md` for the gate, default branch, and worktree rules the orchestrator will quote, and report any it lacks. 5. Show the user only the block the script prints. Add a line only for something unexpected: a refusal, a question from step 3, or a failed check. Tell the user to run `/reload-plugins` or restart, since agents added mid-session are not registered until then; check that one installed agent resolves. diff --git a/skills/setup-agents/scripts/test_install.py b/skills/setup-agents/scripts/test_install.py index 88d25fc..c0715cb 100644 --- a/skills/setup-agents/scripts/test_install.py +++ b/skills/setup-agents/scripts/test_install.py @@ -78,7 +78,7 @@ def main() -> None: assert 'model = "gpt-6-astra"' in (repo / ".codex/agents/planner.toml").read_text() opencode = (repo / ".opencode/agents/planner.md").read_text() assert "model: anthropic/claude-opus-5-5\n" in opencode and "mode: subagent" in opencode - assert "\nskills: follow-the-rules\n" in (repo / ".claude/agents/builder.md").read_text() + assert "\nskills: house-rules\n" in (repo / ".claude/agents/builder.md").read_text() tomllib.loads((repo / ".codex/agents/reviewer.toml").read_text()) assert (repo / ".claude/agents/mine.md").is_file(), "foreign agent removed"