From d475dde3987635f1b6581b455f512b9554da4a2d Mon Sep 17 00:00:00 2001 From: m3tm3re Date: Tue, 17 Feb 2026 18:59:43 +0100 Subject: [PATCH] feat(rules): add rules directory structure and usage documentation - Create rules/{concerns,languages,frameworks}/ directory structure - Add USAGE.md with flake.nix integration examples - Add plan and notepad files for rules-system implementation Refs: T1, T5 of rules-system plan --- .sisyphus/boulder.json | 8 +- .sisyphus/notepads/rules-system/learnings.md | 60 ++ .sisyphus/plans/rules-system.md | 804 +++++++++++++++++++ rules/USAGE.md | 62 ++ rules/concerns/.gitkeep | 0 rules/frameworks/.gitkeep | 0 rules/languages/.gitkeep | 0 7 files changed, 930 insertions(+), 4 deletions(-) create mode 100644 .sisyphus/notepads/rules-system/learnings.md create mode 100644 .sisyphus/plans/rules-system.md create mode 100644 rules/USAGE.md create mode 100644 rules/concerns/.gitkeep create mode 100644 rules/frameworks/.gitkeep create mode 100644 rules/languages/.gitkeep diff --git a/.sisyphus/boulder.json b/.sisyphus/boulder.json index 8b0ec8e..b01752a 100644 --- a/.sisyphus/boulder.json +++ b/.sisyphus/boulder.json @@ -1,9 +1,9 @@ { - "active_plan": "/home/m3tam3re/p/AI/AGENTS/.sisyphus/plans/opencode-memory.md", - "started_at": "2026-02-14T04:43:37.746Z", + "active_plan": "/home/m3tam3re/p/AI/AGENTS/.sisyphus/plans/rules-system.md", + "started_at": "2026-02-17T17:50:08.922Z", "session_ids": [ - "ses_3a5a47a05ffeoNYfz2RARYsHX9" + "ses_393691db2ffe4YZvieMFehJe54" ], - "plan_name": "opencode-memory", + "plan_name": "rules-system", "agent": "atlas" } \ No newline at end of file diff --git a/.sisyphus/notepads/rules-system/learnings.md b/.sisyphus/notepads/rules-system/learnings.md new file mode 100644 index 0000000..9626953 --- /dev/null +++ b/.sisyphus/notepads/rules-system/learnings.md @@ -0,0 +1,60 @@ +# Rules System - Learnings + +## 2026-02-17T17:50 Session Start + +### Architecture Pattern +- Nix helper lives in nixpkgs repo (not AGENTS) - follows ports.nix pattern +- AGENTS repo stays pure content (markdown rule files only) +- Pattern: `{lib}: { mkOpencodeRules = ...; }` + +### Key Files +- nixpkgs: `/home/m3tam3re/p/NIX/nixpkgs/lib/ports.nix` (reference pattern) +- nixos-config: `/home/m3tam3re/p/NIX/nixos-config/home/features/coding/opencode.nix` (deployment) +- AGENTS: `rules/` directory (content) + +### mkOpencodeRules Signature +```nix +mkOpencodeRules { + agents = inputs.agents; # Non-flake input path + languages = [ "python" "typescript" ]; + concerns ? [ "coding-style" "naming" "documentation" "testing" "git-workflow" "project-structure" ]; + frameworks ? [ "n8n" ]; + extraInstructions ? []; +} +``` + +### Consumption Pattern +```nix +let + m3taLib = inputs.m3ta-nixpkgs.lib.${system}; + rules = m3taLib.opencode-rules.mkOpencodeRules { + agents = inputs.agents; + languages = [ "python" ]; + }; +in pkgs.mkShell { shellHook = rules.shellHook; } +``` + +### Wave 1: Directory Structure (2026-02-17T18:54) +- Successfully created rules/ directory with subdirectories: concerns/, languages/, frameworks/ +- Added .gitkeep files to each subdirectory (git needs at least one file to track empty directories) +- Pattern reference: followed skills/ directory structure convention +- USAGE.md already existed in rules/ (created by previous wave) +- AGENTS repo stays pure content - no Nix files added (as planned) +- Verification: ls confirms all three .gitkeep files exist in proper locations + +### Wave 2: Nix Helper Implementation (2026-02-17T19:02) +- Successfully created `/home/m3tam3re/p/NIX/nixpkgs/lib/opencode-rules.nix` +- Followed ports.nix pattern EXACTLY: `{lib}: { mkOpencodeRules = ...; }` +- Function signature: `{ agents, languages ? [], concerns ? [...], frameworks ? [], extraInstructions ? [] }` +- Returns: `{ shellHook, instructions }` +- Instructions list built using map functions for each category (concerns, languages, frameworks, extra) +- ShellHook creates symlink `.opencode-rules` → `${agents}/rules` and generates `opencode.json` with `$schema` +- JSON generation uses `builtins.toJSON opencodeConfig` where opencodeConfig = `{ "$schema" = "..."; inherit instructions; }` +- Comprehensive doc comments added matching ports.nix style (multi-line comments with usage examples) +- All paths relative to project root via `.opencode-rules/` prefix +- Verification passed: + - `nix eval --impure` shows file loads and exposes `mkOpencodeRules` + - Function returns `{ instructions, shellHook }` + - Instructions list builds correctly (concerns + languages + frameworks + extra) + - `nix-instantiate --parse` validates syntax is correct +- ShellHook contains both symlink creation and JSON generation (heredoc pattern) diff --git a/.sisyphus/plans/rules-system.md b/.sisyphus/plans/rules-system.md new file mode 100644 index 0000000..0ba6274 --- /dev/null +++ b/.sisyphus/plans/rules-system.md @@ -0,0 +1,804 @@ +# Centralized Rules & Per-Project Context Injection System + +## TL;DR + +> **Quick Summary**: Create a `rules/` directory in the AGENTS repository containing modular AI coding rules (per-concern + per-language), deployed centrally via Home Manager. A `mkOpencodeRules` Nix helper function lives in the nixpkgs repo (following the existing `ports.nix` → `mkPortHelpers` pattern), generating per-project `opencode.json` via devShell activation. +> +> **Deliverables**: +> - 6 concern rule files (coding-style, naming, documentation, testing, git-workflow, project-structure) +> - 5 language/framework rule files (python, typescript, nix, shell, n8n) +> - `lib/opencode-rules.nix` in nixpkgs repo — `mkOpencodeRules` helper function +> - Updated `lib/default.nix` in nixpkgs repo — imports opencode-rules +> - Updated `opencode.nix` in nixos-config — deploys rules/ alongside existing skills +> - `rules/USAGE.md` — per-project adoption documentation +> +> **Repos Touched**: 3 (AGENTS, nixpkgs, nixos-config) +> **Estimated Effort**: Medium (11 rule files + 3 nix changes + 1 doc) +> **Parallel Execution**: YES — 4 waves +> **Critical Path**: T1-T3 (foundation) → T6-T16 (content) → T17 (verification) + +--- + +## Context + +### Original Request +User wants to streamline their Agent workflow by centrally managing language-specific and framework-specific coding rules in the AGENTS repository, while allowing project-specific overrides. Rules should be injected per-project using Nix flakes + direnv. + +### Interview Summary +**Key Discussions**: +- **Loading strategy**: Always loaded (not lazy) — rules always in context when project activates +- **Composition mechanism**: Nix flake devShell — each project declares languages/frameworks needed +- **Rule granularity**: Per concern with separate language files for deep patterns +- **Override strategy**: Project-level AGENTS.md overrides central rules (OpenCode's native precedence) +- **opencode.json**: No project-specific one exists yet — devShell generates it entirely +- **Nix helper location**: Lives in `m3ta-nixpkgs` repo at `lib/opencode-rules.nix` (follows `ports.nix` pattern) +- **AGENTS repo stays pure content**: No Nix code — only markdown rule files + +**Research Findings**: +- OpenCode `instructions` field in `opencode.json` loads external .md files as always-on context +- Anthropic guide: progressive disclosure, composability, 500-line max, use TOCs for long files +- Best practices: 100-200 lines per file, imperative language, micro-examples (correct/incorrect) +- Rule files benefit from sandwich principle: critical constraints at START and END + +### Metis Review +**Identified Gaps** (addressed): +- **Rule update strategy**: When rules change in AGENTS repo, projects run `nix flake update agents`. Standard Nix flow. +- **Multi-language projects**: `mkOpencodeRules { languages = [ "python" "typescript" ]; }` — list multiple. +- **Context window budget**: ~800-1300 lines total. Well under 1500-line budget. +- **Empty rules selection**: `mkOpencodeRules {}` loads only concern files (defaults to all 6). + +### Architecture Decision: Nix Helper Location +**Decision**: `mkOpencodeRules` lives in **nixpkgs repo** (`/home/m3tam3re/p/NIX/nixpkgs/lib/opencode-rules.nix`), NOT in AGENTS repo. + +**Rationale**: +- nixpkgs already has `lib/ports.nix` → `mkPortHelpers` as an identical pattern +- nixpkgs is already consumed by all configs: `inputs.m3ta-nixpkgs.lib.${system}` +- AGENTS repo stays pure content (markdown + configs), no Nix code +- Projects already have `m3ta-nixpkgs` as a flake input — no new input needed for the helper + +**Consumption pattern** (per-project): +```nix +let + m3taLib = inputs.m3ta-nixpkgs.lib.${system}; + rules = m3taLib.opencode-rules.mkOpencodeRules { + agents = inputs.agents; # Non-flake input with rule content + languages = [ "python" ]; + }; +in pkgs.mkShell { shellHook = rules.shellHook; } +``` + +--- + +## Work Objectives + +### Core Objective +Create a centralized, modular AI coding rules system managed in the AGENTS repo, with a Nix helper in nixpkgs for per-project injection via devShell + direnv. + +### Concrete Deliverables +- `rules/concerns/{coding-style,naming,documentation,testing,git-workflow,project-structure}.md` — in AGENTS repo +- `rules/languages/{python,typescript,nix,shell}.md` — in AGENTS repo +- `rules/frameworks/n8n.md` — in AGENTS repo +- `rules/USAGE.md` — adoption documentation in AGENTS repo +- `lib/opencode-rules.nix` — in nixpkgs repo (`/home/m3tam3re/p/NIX/nixpkgs/`) +- Updated `lib/default.nix` — in nixpkgs repo (add import) +- Updated `opencode.nix` — in nixos-config repo (`/home/m3tam3re/p/NIX/nixos-config/home/features/coding/`) + +### Definition of Done +- [ ] All 11 rule files exist and are under 250 lines each +- [ ] `lib/opencode-rules.nix` in nixpkgs exports `mkOpencodeRules` following `ports.nix` pattern +- [ ] `opencode.nix` deploys `rules/` to `~/.config/opencode/rules/` +- [ ] A project can use `m3taLib.opencode-rules.mkOpencodeRules` in devShell + +### Must Have +- All rule files use imperative language ("Always use...", "Never...") +- Every rule includes micro-examples (correct vs incorrect, 2-3 lines each) +- Concern files are language-agnostic; language subsections are brief pointers +- Language files go deep into toolchain, idioms, anti-patterns +- `mkOpencodeRules` accepts: `{ agents, languages ? [], concerns ? [...], frameworks ? [], extraInstructions ? [] }` +- `mkOpencodeRules` follows `ports.nix` pattern: `{lib}: { mkOpencodeRules = ...}` +- shellHook creates `.opencode-rules` symlink + generates `opencode.json` +- Both `.opencode-rules` and `opencode.json` must be gitignored (documented in USAGE.md) + +### Must NOT Have (Guardrails) +- Rule files MUST NOT exceed 250 lines +- Total loaded rules MUST NOT exceed 1500 lines for any realistic config +- Concern files MUST NOT contain language-specific implementation details +- MUST NOT put Nix code in AGENTS repo — AGENTS stays pure content +- MUST NOT add rule versioning, testing framework, or generator CLI +- MUST NOT create rules for docker, k8s, terraform — out of scope +- MUST NOT modify existing skills, agents, prompts, or commands +- MUST NOT use generic advice ("write clean code", "follow best practices") + +--- + +## Verification Strategy (MANDATORY) + +> **ZERO HUMAN INTERVENTION** — ALL verification is agent-executed. No exceptions. + +### Test Decision +- **Infrastructure exists**: NO (config/documentation repos) +- **Automated tests**: NO +- **Framework**: none + +### QA Policy +Every task MUST include agent-executed QA scenarios. +Evidence saved to `.sisyphus/evidence/task-{N}-{scenario-slug}.{ext}`. + +| Deliverable Type | Verification Tool | Method | +|------------------|-------------------|--------| +| Markdown rule files | Bash (wc, grep) | Line count, micro-examples, imperative language | +| Nix expressions | Bash (nix eval) | Evaluate, check errors | +| Shell integration | Bash | Verify symlink + opencode.json generated | +| Cross-repo | Bash (grep) | Verify entries in correct files | + +--- + +## Execution Strategy + +### Parallel Execution Waves + +``` +Wave 1 (Foundation — 5 tasks, all parallel): +├── Task 1: Create rules/ directory structure in AGENTS repo [quick] +├── Task 2: Create lib/opencode-rules.nix in nixpkgs repo [quick] +├── Task 3: Update lib/default.nix in nixpkgs repo [quick] +├── Task 4: Update opencode.nix in nixos-config repo [quick] +└── Task 5: Create rules/USAGE.md in AGENTS repo [quick] + +Wave 2 (Content — 11 rule files, all parallel): +├── Task 6: concerns/coding-style.md [writing] +├── Task 7: concerns/naming.md [writing] +├── Task 8: concerns/documentation.md [writing] +├── Task 9: concerns/testing.md [writing] +├── Task 10: concerns/git-workflow.md [writing] +├── Task 11: concerns/project-structure.md [writing] +├── Task 12: languages/python.md [writing] +├── Task 13: languages/typescript.md [writing] +├── Task 14: languages/nix.md [writing] +├── Task 15: languages/shell.md [writing] +└── Task 16: frameworks/n8n.md [writing] + +Wave 3 (Verification): +└── Task 17: End-to-end integration test [deep] + +Wave FINAL (Review — 4 parallel): +├── Task F1: Plan compliance audit (oracle) +├── Task F2: Code quality review (unspecified-high) +├── Task F3: Real manual QA (unspecified-high) +└── Task F4: Scope fidelity check (deep) + +Critical Path: T1-T3 → T6-T16 (parallel) → T17 → F1-F4 +Max Concurrent: 11 (Wave 2) +``` + +### Dependency Matrix + +| Task | Depends On | Blocks | Wave | +|------|------------|--------|------| +| 1 | — | 5, 6-16, 17 | 1 | +| 2, 3 | — | 17 | 1 | +| 4 | — | 17 | 1 | +| 5 | 1, 2 | 17 | 1 | +| 6-16 | 1 | 17 | 2 | +| 17 | 2-5, 6-16 | F1-F4 | 3 | +| F1-F4 | 17 | — | FINAL | + +### Agent Dispatch Summary + +| Wave | # Parallel | Tasks and Agent Category | +|------|------------|------------------------| +| 1 | **5** | T1-T5 → `quick` | +| 2 | **11** | T6-T16 → `writing` | +| 3 | **1** | T17 → `deep` | +| FINAL | **4** | F1 → `oracle`, F2,F3 → `unspecified-high`, F4 → `deep` | + +--- + +## TODOs + +- [x] 1. Create rules/ directory structure in AGENTS repo + + **What to do**: + - Create directory structure in `/home/m3tam3re/p/AI/AGENTS/`: `rules/concerns/`, `rules/languages/`, `rules/frameworks/` + - Add `.gitkeep` files to each directory so they're tracked before content is added + - This is the CONTENT repo only — NO Nix code goes here + + **Must NOT do**: + - Do not create any Nix files in AGENTS repo + - Do not create rule content files (those are Wave 2) + + **Recommended Agent Profile**: + - **Category**: `quick` + - **Skills**: [] + + **Parallelization**: + - **Can Run In Parallel**: YES + - **Parallel Group**: Wave 1 (with Tasks 2-5) + - **Blocks**: Tasks 5, 6-16, 17 + - **Blocked By**: None + + **References**: + - `/home/m3tam3re/p/AI/AGENTS/skills/` — existing directory structure pattern + + **Acceptance Criteria**: + + **QA Scenarios (MANDATORY):** + + ``` + Scenario: Directory structure exists + Tool: Bash + Preconditions: None + Steps: + 1. Run `ls /home/m3tam3re/p/AI/AGENTS/rules/concerns/.gitkeep /home/m3tam3re/p/AI/AGENTS/rules/languages/.gitkeep /home/m3tam3re/p/AI/AGENTS/rules/frameworks/.gitkeep` + Expected Result: All 3 .gitkeep files exist + Failure Indicators: "No such file or directory" + Evidence: .sisyphus/evidence/task-1-dirs.txt + + Scenario: No Nix files in AGENTS repo rules/ + Tool: Bash + Preconditions: Dirs created + Steps: + 1. Run `find /home/m3tam3re/p/AI/AGENTS/rules/ -name '*.nix' | wc -l` + Expected Result: Count is 0 + Failure Indicators: Count > 0 + Evidence: .sisyphus/evidence/task-1-no-nix.txt + ``` + + **Commit**: YES + - Message: `feat(rules): add rules directory structure` + - Files: `rules/concerns/.gitkeep`, `rules/languages/.gitkeep`, `rules/frameworks/.gitkeep` + +--- + +- [x] 2. Create `lib/opencode-rules.nix` in nixpkgs repo + + **What to do**: + - Create `/home/m3tam3re/p/NIX/nixpkgs/lib/opencode-rules.nix` + - Follow the EXACT pattern of `lib/ports.nix`: `{lib}: { mkOpencodeRules = ...; }` + - The function must accept: `{ agents, languages ? [], concerns ? [ "coding-style" "naming" "documentation" "testing" "git-workflow" "project-structure" ], frameworks ? [], extraInstructions ? [] }` + - `agents` parameter = the non-flake input (path to AGENTS repo in Nix store) + - It must return: `{ shellHook = "..."; instructions = [...]; }` + - `shellHook` must: (a) create `.opencode-rules` symlink to `${agents}/rules`, (b) generate `opencode.json` with `$schema` and `instructions` fields using `builtins.toJSON` + - `instructions` = list of paths relative to project root via `.opencode-rules/` symlink + - Include comprehensive Nix doc comments (matching ports.nix style) + + **Must NOT do**: + - Do not deviate from ports.nix pattern + - Do not put any code in AGENTS repo + + **Recommended Agent Profile**: + - **Category**: `quick` + - Reason: One Nix file following established pattern + - **Skills**: [] + + **Parallelization**: + - **Can Run In Parallel**: YES + - **Parallel Group**: Wave 1 (with Tasks 1, 3-5) + - **Blocks**: Tasks 5, 17 + - **Blocked By**: None + + **References**: + + **Pattern References**: + - `/home/m3tam3re/p/NIX/nixpkgs/lib/ports.nix` — MUST follow this exact pattern: `{lib}: { mkPortHelpers = portsConfig: let ... in { ... }; }` + - `/home/m3tam3re/p/NIX/nixpkgs/lib/default.nix` — shows how lib modules are imported: `import ./ports.nix {inherit lib;}` + - `/home/m3tam3re/p/NIX/nixpkgs/flake.nix:73-77` — shows how lib is exposed: `lib = forAllSystems (system: ... import ./lib {lib = pkgs.lib;});` + + **External References**: + - OpenCode rules docs: `https://opencode.ai/docs/rules/` — `instructions` field accepts relative paths + + **WHY Each Reference Matters**: + - `ports.nix` is the canonical pattern for lib functions in this repo — `{lib}:` signature, doc comments, nested `let ... in` + - `default.nix` shows how the new module gets wired in + - `flake.nix` confirms how consumers access it: `m3ta-nixpkgs.lib.${system}.opencode-rules.mkOpencodeRules` + + **Acceptance Criteria**: + + **QA Scenarios (MANDATORY):** + + ``` + Scenario: opencode-rules.nix evaluates without errors + Tool: Bash + Preconditions: File created + Steps: + 1. Run `nix eval --impure --expr 'let pkgs = import {}; lib = (import /home/m3tam3re/p/NIX/nixpkgs/lib/opencode-rules.nix {lib = pkgs.lib;}); in builtins.attrNames lib' 2>&1` + Expected Result: Output contains "mkOpencodeRules" + Failure Indicators: "error:" in output + Evidence: .sisyphus/evidence/task-2-eval.txt + + Scenario: mkOpencodeRules generates correct paths + Tool: Bash + Preconditions: File created + Steps: + 1. Run `nix eval --impure --json --expr 'let pkgs = import {}; lib = (import /home/m3tam3re/p/NIX/nixpkgs/lib/opencode-rules.nix {lib = pkgs.lib;}); in (lib.mkOpencodeRules { agents = /home/m3tam3re/p/AI/AGENTS; languages = ["python" "typescript"]; frameworks = ["n8n"]; }).instructions'` + Expected Result: JSON array with 9 paths (6 concerns + 2 languages + 1 framework), all starting with ".opencode-rules/" + Failure Indicators: Wrong count, wrong prefix, error + Evidence: .sisyphus/evidence/task-2-paths.txt + + Scenario: Default (empty languages) works + Tool: Bash + Preconditions: File created + Steps: + 1. Run `nix eval --impure --json --expr 'let pkgs = import {}; lib = (import /home/m3tam3re/p/NIX/nixpkgs/lib/opencode-rules.nix {lib = pkgs.lib;}); in (lib.mkOpencodeRules { agents = /home/m3tam3re/p/AI/AGENTS; }).instructions'` + Expected Result: JSON array with 6 paths (concerns only) + Failure Indicators: Extra paths, error + Evidence: .sisyphus/evidence/task-2-defaults.txt + + Scenario: shellHook generates valid JSON + Tool: Bash + Preconditions: File created + Steps: + 1. Run `nix eval --impure --raw --expr 'let pkgs = import {}; lib = (import /home/m3tam3re/p/NIX/nixpkgs/lib/opencode-rules.nix {lib = pkgs.lib;}); in (lib.mkOpencodeRules { agents = /home/m3tam3re/p/AI/AGENTS; languages = ["python"]; }).shellHook' | sh -c 'eval "$(cat)"' && python3 -m json.tool opencode.json` + Expected Result: Valid JSON output with "$schema" and "instructions" fields + Failure Indicators: JSON parse error, missing fields + Evidence: .sisyphus/evidence/task-2-json.txt + ``` + + **Commit**: YES + - Message: `feat(lib): add opencode-rules helper for per-project rule injection` + - Files: `lib/opencode-rules.nix` + - Pre-commit: `nix eval --impure --expr '...'` + +--- + +- [x] 3. Update `lib/default.nix` in nixpkgs repo + + **What to do**: + - Add one line to `/home/m3tam3re/p/NIX/nixpkgs/lib/default.nix` to import opencode-rules: + `opencode-rules = import ./opencode-rules.nix {inherit lib;};` + - Place it after the existing `ports = import ./ports.nix {inherit lib;};` line + - Update the comment at line 10 to remove it (it's a placeholder) + + **Must NOT do**: + - Do not modify the ports import + - Do not change the function signature `{lib}:` + + **Recommended Agent Profile**: + - **Category**: `quick` + - **Skills**: [] + + **Parallelization**: + - **Can Run In Parallel**: YES (but logically pairs with Task 2) + - **Parallel Group**: Wave 1 + - **Blocks**: Task 17 + - **Blocked By**: Task 2 (opencode-rules.nix must exist first) + + **References**: + - `/home/m3tam3re/p/NIX/nixpkgs/lib/default.nix:6-12` — current file content, add after line 8 + + **Acceptance Criteria**: + + **QA Scenarios (MANDATORY):** + + ``` + Scenario: default.nix imports opencode-rules + Tool: Bash + Preconditions: Both files updated + Steps: + 1. Run `grep 'opencode-rules' /home/m3tam3re/p/NIX/nixpkgs/lib/default.nix` + Expected Result: Line shows `opencode-rules = import ./opencode-rules.nix {inherit lib;};` + Failure Indicators: No match + Evidence: .sisyphus/evidence/task-3-import.txt + + Scenario: Full lib evaluates + Tool: Bash + Preconditions: Both files updated + Steps: + 1. Run `nix eval --impure --expr 'let pkgs = import {}; m3taLib = import /home/m3tam3re/p/NIX/nixpkgs/lib {lib = pkgs.lib;}; in builtins.attrNames m3taLib' 2>&1` + Expected Result: Output includes both "ports" and "opencode-rules" + Failure Indicators: Missing "opencode-rules" or error + Evidence: .sisyphus/evidence/task-3-full-lib.txt + ``` + + **Commit**: YES (groups with Task 2) + - Message: `feat(lib): add opencode-rules helper for per-project rule injection` + - Files: `lib/default.nix`, `lib/opencode-rules.nix` + +--- + +- [x] 4. Update opencode.nix in nixos-config repo + + **What to do**: + - Add `rules/` deployment to `xdg.configFile` in `/home/m3tam3re/p/NIX/nixos-config/home/features/coding/opencode.nix` + - Add entry: `"opencode/rules" = { source = "${inputs.agents}/rules"; recursive = true; };` + - Place it alongside existing entries for commands, context, prompts, skills (lines 2-18) + + **Must NOT do**: + - Do not modify any existing entries + - Do not change agents, MCP, providers, or oh-my-opencode config + - Do not run `home-manager switch` + + **Recommended Agent Profile**: + - **Category**: `quick` + - **Skills**: [] + + **Parallelization**: + - **Can Run In Parallel**: YES + - **Parallel Group**: Wave 1 + - **Blocks**: Task 17 + - **Blocked By**: None + + **References**: + - `/home/m3tam3re/p/NIX/nixos-config/home/features/coding/opencode.nix:2-18` — existing xdg.configFile entries + + **Acceptance Criteria**: + + **QA Scenarios (MANDATORY):** + + ``` + Scenario: opencode.nix contains rules entry + Tool: Bash + Preconditions: File updated + Steps: + 1. Run `grep -c 'opencode/rules' /home/m3tam3re/p/NIX/nixos-config/home/features/coding/opencode.nix` + 2. Run `grep -c 'opencode/commands\|opencode/context\|opencode/prompts\|opencode/skills' /home/m3tam3re/p/NIX/nixos-config/home/features/coding/opencode.nix` + Expected Result: Rules count is 1, existing count is 4 (all preserved) + Failure Indicators: Count mismatch + Evidence: .sisyphus/evidence/task-4-opencode-nix.txt + ``` + + **Commit**: YES + - Message: `feat(opencode): deploy rules/ to ~/.config/opencode/rules/ via home-manager` + - Files: `opencode.nix` + +--- + +- [x] 5. Create `rules/USAGE.md` in AGENTS repo + + **What to do**: + - Document how to use `mkOpencodeRules` in a project's `flake.nix` + - Show the nixpkgs consumption pattern: `m3taLib.opencode-rules.mkOpencodeRules { agents = inputs.agents; languages = ["python"]; }` + - Complete example `flake.nix` devShell snippet showing: `inputs.agents` + `inputs.m3ta-nixpkgs` + `mkOpencodeRules` + `shellHook` + - Document `.gitignore` additions: `.opencode-rules` and `opencode.json` + - Explain project-level `AGENTS.md` overrides + - Explain update flow: `nix flake update agents` + - Keep concise: max 100 lines + + **Must NOT do**: + - Do not create a README.md (repo anti-pattern) + - Do not reference `rules/default.nix` — the helper lives in nixpkgs, not AGENTS + + **Recommended Agent Profile**: + - **Category**: `quick` + - **Skills**: [] + + **Parallelization**: + - **Can Run In Parallel**: YES + - **Parallel Group**: Wave 1 + - **Blocks**: Task 17 + - **Blocked By**: Tasks 1, 2 (needs to reference both structures) + + **References**: + - `/home/m3tam3re/p/AI/AGENTS/AGENTS.md` — repo documentation style (concise, code-heavy) + - `/home/m3tam3re/p/NIX/nixpkgs/lib/ports.nix:1-42` — the doc comment style used for lib functions + - OpenCode rules docs: `https://opencode.ai/docs/rules/` — `instructions` field + + **Acceptance Criteria**: + + **QA Scenarios (MANDATORY):** + + ``` + Scenario: USAGE.md has required content + Tool: Bash + Preconditions: File created + Steps: + 1. Run `wc -l /home/m3tam3re/p/AI/AGENTS/rules/USAGE.md` + 2. Run `grep -c 'm3ta-nixpkgs\|mkOpencodeRules\|gitignore\|AGENTS.md\|nix flake update' /home/m3tam3re/p/AI/AGENTS/rules/USAGE.md` + Expected Result: Under 100 lines, key terms >= 5 + Failure Indicators: Over 100 lines or missing key concepts + Evidence: .sisyphus/evidence/task-5-usage.txt + ``` + + **Commit**: YES (groups with T1) + - Message: `feat(rules): add rules directory structure and usage documentation` + - Files: `rules/USAGE.md`, `rules/concerns/.gitkeep`, `rules/languages/.gitkeep`, `rules/frameworks/.gitkeep` + +--- + +- [ ] 6. Create `rules/concerns/coding-style.md` + + **What to do**: + - Write coding style rules: code formatting, patterns/anti-patterns, error handling, type safety, function design, DRY/SOLID + - Imperative language ("Always...", "Never...", "Prefer..."), micro-examples (`Correct:` / `Incorrect:`) + - Keep under 200 lines, sandwich principle (critical rules at start and end) + + **Must NOT do**: No language-specific toolchain details, no generic advice ("write clean code"), max 200 lines + + **Recommended Agent Profile**: `writing`, Skills: [] + **Parallelization**: Wave 2, parallel with T7-T16. Blocks T17. Blocked by T1. + + **References**: + - `/home/m3tam3re/p/AI/AGENTS/skills/skill-creator/SKILL.md` — documentation density example + - Awesome Cursorrules: `https://github.com/PatrickJS/awesome-cursorrules` + + **Acceptance Criteria**: + ``` + Scenario: Quality check + Tool: Bash + Steps: + 1. `wc -l` → under 200 + 2. `grep -c 'Correct:\|Incorrect:\|Always\|Never\|Prefer'` → >= 10 + 3. `grep -c '```'` → >= 6 (3+ example pairs) + 4. `grep -ic 'write clean code\|follow best practices'` → 0 + Evidence: .sisyphus/evidence/task-6-coding-style.txt + ``` + **Commit**: NO (groups with Wave 2 commit in T17) + +--- + +- [ ] 7. Create `rules/concerns/naming.md` + + **What to do**: + - Naming conventions: files, variables, functions, classes, modules, constants + - Per-language table (Python=snake_case, TS=camelCase, Nix=camelCase, Shell=UPPER_SNAKE) + - Keep under 150 lines + + **Must NOT do**: No toolchain details, max 150 lines + + **Recommended Agent Profile**: `writing`, Skills: [] + **Parallelization**: Wave 2. Blocks T17. Blocked by T1. + + **References**: `/home/m3tam3re/p/AI/AGENTS/AGENTS.md:58-62` — existing naming conventions + + **Acceptance Criteria**: + ``` + Scenario: `wc -l` → under 150, `grep -c 'snake_case\|camelCase\|PascalCase\|UPPER_SNAKE'` → >= 4 + Evidence: .sisyphus/evidence/task-7-naming.txt + ``` + **Commit**: NO + +--- + +- [ ] 8. Create `rules/concerns/documentation.md` + + **What to do**: When to document, docstring formats, inline comment philosophy (WHY not WHAT), README standards. Under 150 lines. + **Recommended Agent Profile**: `writing` + **Parallelization**: Wave 2. Blocked by T1. + **References**: `/home/m3tam3re/p/AI/AGENTS/AGENTS.md` — repo's own style + **Acceptance Criteria**: `wc -l` < 150, `grep -c 'WHY\|WHAT\|Correct:\|Incorrect:'` >= 4 + **Commit**: NO + +--- + +- [ ] 9. Create `rules/concerns/testing.md` + + **What to do**: Arrange-act-assert, behavior vs implementation testing, mocking philosophy, coverage, TDD. Under 200 lines. + **Recommended Agent Profile**: `writing` + **Parallelization**: Wave 2. Blocked by T1. + **References**: `/home/m3tam3re/p/AI/AGENTS/AGENTS.md:73-82` — existing test philosophy + **Acceptance Criteria**: `wc -l` < 200, `grep -ic 'arrange\|act\|assert\|mock\|behavior'` >= 4 + **Commit**: NO + +--- + +- [ ] 10. Create `rules/concerns/git-workflow.md` + + **What to do**: Conventional commits, branch naming, PR descriptions, squash vs merge. Under 120 lines. + **Recommended Agent Profile**: `writing`, Skills: [`git-master`] + **Parallelization**: Wave 2. Blocked by T1. + **References**: `https://www.conventionalcommits.org/en/v1.0.0/` + **Acceptance Criteria**: `wc -l` < 120, `grep -c 'feat\|fix\|refactor\|docs\|chore'` >= 5 + **Commit**: NO + +--- + +- [ ] 11. Create `rules/concerns/project-structure.md` + + **What to do**: Directory layout, module organization, entry points, config placement. Per-type: Python (src layout), TS (src/), Nix (modules/). Under 120 lines. + **Recommended Agent Profile**: `writing` + **Parallelization**: Wave 2. Blocked by T1. + **References**: `/home/m3tam3re/p/AI/AGENTS/AGENTS.md:24-38` — repo structure + **Acceptance Criteria**: `wc -l` < 120 + **Commit**: NO + +--- + +- [ ] 12. Create `rules/languages/python.md` + + **What to do**: + - Deep Python patterns: `uv` (pkg mgmt), `ruff` (lint/fmt), `pyright` (types), `pytest` + `hypothesis`, Pydantic for data boundaries + - Idioms: comprehensions, context managers, generators, f-strings + - Anti-patterns: bare except, mutable defaults, global state, star imports + - Project setup: `pyproject.toml`, src layout + - Under 250 lines with micro-examples + + **Must NOT do**: No general coding style (covered in concerns/), no Django/Flask/FastAPI, max 250 lines + + **Recommended Agent Profile**: `writing` + **Parallelization**: Wave 2. Blocked by T1. + + **References**: + - `/home/m3tam3re/p/AI/AGENTS/AGENTS.md:60` — existing Python conventions (shebang, docstrings) + - Ruff docs: `https://docs.astral.sh/ruff/`, uv docs: `https://docs.astral.sh/uv/` + + **Acceptance Criteria**: `wc -l` < 250, `grep -c 'ruff\|uv\|pytest\|pydantic\|pyright'` >= 4, `grep -c '```python'` >= 5, no "pythonic"/"best practice" + **Commit**: NO + +--- + +- [ ] 13. Create `rules/languages/typescript.md` + + **What to do**: + - Strict mode (`strict: true`, `noUncheckedIndexedAccess`), discriminated unions, branded types, `satisfies`, `as const` + - Modern: `using`, `Promise.withResolvers()`, `Object.groupBy()` + - Toolchain: `bun`/`tsx`, `biome`/`eslint` + - Anti-patterns: `as any`, `@ts-ignore`, `!` assertion, `enum` (prefer union) + - Under 250 lines + + **Must NOT do**: No React/Next.js, max 250 lines + + **Recommended Agent Profile**: `writing` + **Parallelization**: Wave 2. Blocked by T1. + **Acceptance Criteria**: `wc -l` < 250, `grep -c 'strict\|as any\|ts-ignore\|discriminated\|satisfies'` >= 4, `grep -c '```ts'` >= 5 + **Commit**: NO + +--- + +- [ ] 14. Create `rules/languages/nix.md` + + **What to do**: + - Flake structure, module patterns (`{ config, lib, pkgs, ... }:`), `mkIf`/`mkMerge` + - Formatting: `alejandra`, naming: camelCase + - Anti-patterns: `with pkgs;`, `builtins.fetchTarball`, impure ops + - Home Manager patterns, overlays + - Under 200 lines + + **Recommended Agent Profile**: `writing` + **Parallelization**: Wave 2. Blocked by T1. + + **References**: + - `/home/m3tam3re/p/NIX/nixos-config/home/features/coding/opencode.nix` — user's actual Nix style + - `/home/m3tam3re/p/NIX/nixpkgs/lib/ports.nix` — well-structured Nix code example + + **Acceptance Criteria**: `wc -l` < 200, `grep -c 'flake\|mkShell\|alejandra\|with pkgs\|overlay'` >= 4 + **Commit**: NO + +--- + +- [ ] 15. Create `rules/languages/shell.md` + + **What to do**: `set -euo pipefail`, shellcheck, quoting, local vars, POSIX portability, `#!/usr/bin/env bash`. Under 120 lines. + **Recommended Agent Profile**: `writing` + **Parallelization**: Wave 2. Blocked by T1. + **References**: `/home/m3tam3re/p/AI/AGENTS/AGENTS.md:61`, `/home/m3tam3re/p/AI/AGENTS/scripts/test-skill.sh` + **Acceptance Criteria**: `wc -l` < 120, `grep -c 'set -euo pipefail\|shellcheck\|#!/usr/bin/env'` >= 2 + **Commit**: NO + +--- + +- [ ] 16. Create `rules/frameworks/n8n.md` + + **What to do**: Workflow design, node patterns, naming, Error Trigger, data patterns, security. Under 120 lines. + **Recommended Agent Profile**: `writing` + **Parallelization**: Wave 2. Blocked by T1. + **References**: n8n docs: `https://docs.n8n.io/` + **Acceptance Criteria**: `wc -l` < 120, `grep -c 'workflow\|node\|Error Trigger\|webhook\|credential'` >= 4 + **Commit**: NO + +--- + +- [ ] 17. End-to-end integration test + commits + + **What to do**: + 1. Verify all 11 rule files exist and meet line count limits + 2. Verify `lib/opencode-rules.nix` in nixpkgs evaluates correctly for: empty, single-lang, multi-lang, with-frameworks + 3. Verify full lib import works: `m3taLib.opencode-rules.mkOpencodeRules` + 4. Verify generated `opencode.json` is valid JSON with correct `instructions` paths + 5. Verify all instruction paths resolve to real files in AGENTS repo rules/ + 6. Verify total context budget: all concerns + 1 language < 1500 lines + 7. Verify `opencode.nix` has the rules deployment entry + 8. Commit all Wave 2 rule files as a single commit in AGENTS repo + + **Must NOT do**: Do not run `home-manager switch`, do not modify files, do not create test projects + + **Recommended Agent Profile**: `deep`, Skills: [`git-master`] + **Parallelization**: Wave 3 (sequential). Blocks F1-F4. Blocked by T2-T5, T6-T16. + + **References**: + - `/home/m3tam3re/p/NIX/nixpkgs/lib/opencode-rules.nix` — Nix helper to evaluate + - `/home/m3tam3re/p/NIX/nixos-config/home/features/coding/opencode.nix` — deployment config + + **Acceptance Criteria**: + + **QA Scenarios (MANDATORY):** + + ``` + Scenario: All rule files exist and meet limits + Tool: Bash + Steps: + 1. For each of 11 files: `wc -l` and verify under limit + Expected Result: All 11 files present, all under limits + Evidence: .sisyphus/evidence/task-17-inventory.txt + + Scenario: Full lib integration + Tool: Bash + Steps: + 1. Run `nix eval --impure --json --expr 'let pkgs = import {}; m3taLib = import /home/m3tam3re/p/NIX/nixpkgs/lib {lib = pkgs.lib;}; in (m3taLib.opencode-rules.mkOpencodeRules { agents = /home/m3tam3re/p/AI/AGENTS; languages = ["python" "typescript" "nix" "shell"]; frameworks = ["n8n"]; }).instructions'` + Expected Result: JSON array with 11 paths (6 concerns + 4 langs + 1 framework) + Failure Indicators: Wrong count, error + Evidence: .sisyphus/evidence/task-17-full-integration.txt + + Scenario: All paths resolve to real files + Tool: Bash + Steps: + 1. For each path in instructions output: verify the corresponding file exists under `rules/` + Expected Result: All paths resolve, none missing + Evidence: .sisyphus/evidence/task-17-paths-resolve.txt + + Scenario: Total context budget + Tool: Bash + Steps: + 1. `cat /home/m3tam3re/p/AI/AGENTS/rules/concerns/*.md | wc -l` + 2. `wc -l < /home/m3tam3re/p/AI/AGENTS/rules/languages/python.md` + 3. Sum must be < 1500 + Expected Result: Total under 1500 + Evidence: .sisyphus/evidence/task-17-budget.txt + ``` + + **Commit**: YES + - Message: `feat(rules): add initial rule files for all concerns, languages, and frameworks` + - Files: all `rules/**/*.md` files (11 total) + - Repo: AGENTS + +--- + +## Final Verification Wave (MANDATORY — after ALL implementation tasks) + +> 4 review agents run in PARALLEL. ALL must APPROVE. Rejection → fix → re-run. + +- [ ] F1. **Plan Compliance Audit** — `oracle` + For each "Must Have": verify implementation exists. For each "Must NOT Have": search for violations. Check evidence files. Compare deliverables across all 3 repos. + Output: `Must Have [N/N] | Must NOT Have [N/N] | Tasks [N/N] | VERDICT` + +- [ ] F2. **Code Quality Review** — `unspecified-high` + Rule files: no generic advice, has examples, consistent tone, under limits. Nix: valid syntax, correct paths, edge cases. USAGE.md: accurate. + Output: `Files [N clean/N issues] | VERDICT` + +- [ ] F3. **Real Manual QA** — `unspecified-high` + Run `nix eval` on opencode-rules.nix via full lib import with various configs. Verify JSON. Check rule content quality. Save to `.sisyphus/evidence/final-qa/`. + Output: `Scenarios [N/N pass] | VERDICT` + +- [ ] F4. **Scope Fidelity Check** — `deep` + For each task: "What to do" vs actual file. 1:1 match. No creep. Check "Must NOT do". Flag unaccounted changes across all 3 repos. + Output: `Tasks [N/N compliant] | Unaccounted [CLEAN/N files] | VERDICT` + +--- + +## Commit Strategy + +| After Task(s) | Repo | Message | Files | +|---------------|------|---------|-------| +| 1, 5 | AGENTS | `feat(rules): add rules directory structure and usage documentation` | `rules/USAGE.md`, `rules/{concerns,languages,frameworks}/.gitkeep` | +| 2, 3 | nixpkgs | `feat(lib): add opencode-rules helper for per-project rule injection` | `lib/opencode-rules.nix`, `lib/default.nix` | +| 4 | nixos-config | `feat(opencode): deploy rules/ to ~/.config/opencode/rules/` | `opencode.nix` | +| 17 | AGENTS | `feat(rules): add initial rule files for concerns, languages, and frameworks` | all `rules/**/*.md` (11 files) | + +--- + +## Success Criteria + +### Verification Commands +```bash +# All rule files exist (AGENTS repo) +ls rules/concerns/*.md rules/languages/*.md rules/frameworks/*.md + +# Context budget +cat rules/concerns/*.md rules/languages/python.md | wc -l # Expected: < 1500 + +# Nix helper via full lib (nixpkgs) +nix eval --impure --json --expr 'let pkgs = import {}; m3taLib = import /path/to/nixpkgs/lib {lib = pkgs.lib;}; in (m3taLib.opencode-rules.mkOpencodeRules { agents = /path/to/AGENTS; languages = ["python"]; }).instructions' + +# opencode.nix has rules entry (nixos-config) +grep 'opencode/rules' /home/m3tam3re/p/NIX/nixos-config/home/features/coding/opencode.nix +``` + +### Final Checklist +- [ ] All 11 rule files present and under line limits +- [ ] All rule files use imperative language with micro-examples +- [ ] `lib/opencode-rules.nix` in nixpkgs follows ports.nix pattern exactly +- [ ] `lib/default.nix` imports opencode-rules +- [ ] `opencode.nix` deploys rules/ alongside skills/commands/context/prompts +- [ ] `rules/USAGE.md` documents nixpkgs consumption pattern correctly +- [ ] No Nix code in AGENTS repo +- [ ] No existing files modified (except lib/default.nix +1 line, opencode.nix +3 lines) +- [ ] Total loaded context under 1500 lines for any realistic configuration diff --git a/rules/USAGE.md b/rules/USAGE.md new file mode 100644 index 0000000..6ae994d --- /dev/null +++ b/rules/USAGE.md @@ -0,0 +1,62 @@ +# Opencode Rules Usage + +Add AI coding rules to your project via `mkOpencodeRules`. + +## flake.nix Setup + +```nix +{ + inputs = { + nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable"; + m3ta-nixpkgs.url = "git+https://code.m3ta.dev/m3tam3re/nixpkgs"; + agents = { + url = "git+https://code.m3ta.dev/m3tam3re/AGENTS"; + flake = false; + }; + }; + + outputs = { self, nixpkgs, m3ta-nixpkgs, agents, ... }: + let + system = "x86_64-linux"; + pkgs = nixpkgs.legacyPackages.${system}; + m3taLib = m3ta-nixpkgs.lib.${system}; + in { + devShells.${system}.default = let + rules = m3taLib.opencode-rules.mkOpencodeRules { + inherit agents; + languages = [ "python" "typescript" ]; + frameworks = [ "n8n" ]; + }; + in pkgs.mkShell { + shellHook = rules.shellHook; + }; + }; +} +``` + +## Parameters + +- `agents` (required): Path to AGENTS repo flake input +- `languages` (optional): List of language names (e.g., `["python" "typescript"]`) +- `concerns` (optional): Rule categories (default: all standard concerns) +- `frameworks` (optional): List of framework names (e.g., `["n8n" "django"]`) +- `extraInstructions` (optional): Additional instruction file paths + +## .gitignore + +Add to your project's `.gitignore`: +``` +.opencode-rules +opencode.json +``` + +## Project Overrides + +Create `AGENTS.md` in your project root to override central rules. OpenCode applies project-level rules with precedence over central ones. + +## Updating Rules + +When central rules are updated: +```bash +nix flake update agents +``` diff --git a/rules/concerns/.gitkeep b/rules/concerns/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/rules/frameworks/.gitkeep b/rules/frameworks/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/rules/languages/.gitkeep b/rules/languages/.gitkeep new file mode 100644 index 0000000..e69de29