1680 lines
70 KiB
Markdown
1680 lines
70 KiB
Markdown
# Harness-Agnostic Agent Migration
|
|
|
|
## TL;DR
|
|
|
|
> **Quick Summary**: Migrate AGENTS repo from OpenCode-specific agents.json to a tool-agnostic canonical format (agent.toml + system-prompt.md per agent). Build Nix rendering pipeline in m3ta-nixpkgs that generates tool-specific configs for OpenCode, Claude Code, and Pi. Support system-level (home-manager) and project-level (flake.nix + direnv).
|
|
>
|
|
> **Deliverables**:
|
|
> - 6 canonical agent definitions in AGENTS repo (TOML + Markdown)
|
|
> - 3 tool renderers in m3ta-nixpkgs (OpenCode, Claude Code, Pi)
|
|
> - Home-manager modules per tool replacing current opencode.nix
|
|
> - Project-level lib functions for flake.nix + direnv usage
|
|
> - Backward-compatible bridge during migration
|
|
>
|
|
> **Estimated Effort**: Large
|
|
> **Parallel Execution**: YES — 4 waves
|
|
> **Critical Path**: TOML spike → canonical agents → lib/agents.nix → per-tool HM modules → golden file verification
|
|
|
|
---
|
|
|
|
## Context
|
|
|
|
### Original Request
|
|
Restructure AGENTS repo to be harness-agnostic so the same agent definitions, skills, prompts work across OpenCode, Claude Code, Codex, Pi, and future coding agents. Build corresponding Nix infrastructure in m3ta-nixpkgs for system-level and project-level consumption.
|
|
|
|
### Interview Summary
|
|
**Key Discussions**:
|
|
- YAML rejected for canonical format — TOML chosen (native `builtins.fromTOML`, no IFD)
|
|
- Renderers belong in m3ta-nixpkgs, not AGENTS repo (AGENTS stays pure data)
|
|
- OpenCode + Claude Code + Pi renderers now; Codex/Aider later on demand
|
|
- Two-level permission model: simple intent + optional rules array for glob patterns
|
|
- mkOpencodeRules renamed to mkCodingRules (backward-compat alias)
|
|
- All 6 agents migrated to canonical TOML format
|
|
- opencode.nix replaced by new per-tool modules (but non-agent OpenCode config kept separate)
|
|
- Verification: nix flake check + rendered OpenCode output must match golden file
|
|
- Project-level: lib functions returning derivations, usable via shellHook in devShells
|
|
|
|
**Research Findings**:
|
|
- **OpenCode**: Now supports file-based agents (`.opencode/agent/*.md` with YAML frontmatter) — modern path, avoids config.json embedding
|
|
- **Claude Code**: Subagents require `name` (kebab-case) + `description` as mandatory frontmatter fields
|
|
- **Pi**: No subagent concept. Uses AGENTS.md/CLAUDE.md for instructions, SYSTEM.md for prompt override, same SKILL.md format as OpenCode
|
|
- **Codex**: config.toml + AGENTS.md only, no agent definitions — single-agent tool
|
|
- **Aider**: .aider.conf.yml + read: lists, no agents/permissions/skills
|
|
- **TOML in Nix**: `builtins.fromTOML` supports TOML 1.0.0 strict. No datetime fields, no multi-line inline tables.
|
|
|
|
### Metis Review
|
|
**Identified Gaps** (addressed):
|
|
- **oh-my-opencode.json ownership**: Non-agent OpenCode config stays in slimmed opencode.nix (not in agents.nix)
|
|
- **Pi has no subagents**: Pi renderer produces AGENTS.md + SYSTEM.md from primary agent only. Subagents skipped.
|
|
- **Claude Code name format**: Renderer must slugify to `[a-z0-9-]+`
|
|
- **Model string formats differ**: Need mapping table (canonical → tool-specific)
|
|
- **OpenCode file-based agents**: Modern path via `.opencode/agent/*.md` preferred over config.json embedding
|
|
- **TOML feasibility risk**: Must test Chiron-Forge's 15+ bash glob patterns FIRST
|
|
- **Phase boundary enforced**: agents only (no skills/rules/MCP migration in this plan)
|
|
- **Backward-compat bridge**: `lib.agentsJson` in AGENTS repo produces old JSON during transition
|
|
- **Partial migration hazard**: Version check in nixpkgs to handle old AGENTS input gracefully
|
|
|
|
---
|
|
|
|
## Work Objectives
|
|
|
|
### Core Objective
|
|
Transform the AGENTS repository into a tool-agnostic data repository and build a Nix rendering pipeline that generates tool-specific configurations for multiple coding agents.
|
|
|
|
### Concrete Deliverables
|
|
- `AGENTS/agents/{chiron,chiron-forge,hermes,athena,apollo,calliope}/agent.toml` — 6 canonical agent definitions
|
|
- `AGENTS/agents/{name}/system-prompt.md` — 6 system prompts (byte-identical to current .txt files)
|
|
- `AGENTS/flake.nix` — Updated with `lib.loadAgents` and backward-compat `lib.agentsJson`
|
|
- `nixpkgs/lib/agents.nix` — `loadCanonical` + 3 renderer functions
|
|
- `nixpkgs/modules/home-manager/coding/agents/opencode.nix` — OpenCode HM sub-module
|
|
- `nixpkgs/modules/home-manager/coding/agents/claude-code.nix` — Claude Code HM sub-module
|
|
- `nixpkgs/modules/home-manager/coding/agents/pi.nix` — Pi HM sub-module
|
|
- `nixpkgs/modules/home-manager/coding/opencode.nix` — Slimmed (non-agent config only)
|
|
- `nixpkgs/lib/coding-rules.nix` — Renamed from opencode-rules.nix with backward-compat alias
|
|
|
|
### Definition of Done
|
|
- [ ] `nix flake check` passes on both repos
|
|
- [ ] Rendered OpenCode agent output is semantically equivalent to current agents.json (golden file diff = 0)
|
|
- [ ] All 6 agents parse successfully via `builtins.fromTOML`
|
|
- [ ] Claude Code renderer produces valid MD files with required frontmatter
|
|
- [ ] Pi renderer produces valid AGENTS.md + optional settings.json
|
|
- [ ] System prompt content is byte-identical to current .txt files
|
|
- [ ] `nix fmt` (alejandra) produces no changes
|
|
- [ ] `lib.mkOpencodeSkills` still works unchanged
|
|
|
|
### Must Have
|
|
- All 6 agents in canonical TOML format with system-prompt.md
|
|
- OpenCode renderer producing `.opencode/agent/*.md` file-based agents
|
|
- Claude Code renderer producing `.claude/agents/*.md` with valid YAML frontmatter
|
|
- Pi renderer producing AGENTS.md + SYSTEM.md from primary agent
|
|
- Per-machine model overrides via home-manager
|
|
- Backward-compatible bridge (`lib.agentsJson`) during transition
|
|
- Project-level `renderForTool` lib function for flake.nix + direnv
|
|
|
|
### Must NOT Have (Guardrails)
|
|
- No YAML files as canonical source (TOML only — no IFD)
|
|
- No renderer code in AGENTS repo (renderers live in nixpkgs)
|
|
- No Codex or Aider renderers (design for extensibility, implement only 3)
|
|
- No MCP configuration in agent.toml (MCP is tool-specific infrastructure)
|
|
- No prompt content changes during migration (byte-identical rename only)
|
|
- No skills/rules/context migration in this plan (separate concern)
|
|
- No `mkOpencodeSkills` changes (stays as-is)
|
|
- No datetime fields in TOML schema (requires experimental Nix flag)
|
|
- No multi-line inline tables in TOML (not supported by Nix's TOML 1.0.0)
|
|
- No generic permission translation DSL (each renderer hard-codes its own mapping)
|
|
- No monolithic home-manager module (separate sub-module per tool)
|
|
|
|
---
|
|
|
|
## Verification Strategy (MANDATORY)
|
|
|
|
> **ZERO HUMAN INTERVENTION** — ALL verification is agent-executed. No exceptions.
|
|
|
|
### Test Decision
|
|
- **Infrastructure exists**: YES — Nix evaluation + alejandra formatter
|
|
- **Automated tests**: Nix eval comparison (golden file diff)
|
|
- **Framework**: `nix eval`, `jq --sort-keys`, `diff`, `python3` for YAML validation
|
|
|
|
### QA Policy
|
|
Every task MUST include agent-executed QA scenarios.
|
|
Evidence saved to `.sisyphus/evidence/task-{N}-{scenario-slug}.{ext}`.
|
|
|
|
- **Nix evaluation**: Use Bash (nix eval) — Evaluate expressions, compare outputs
|
|
- **File validation**: Use Bash (python3/jq) — Parse YAML frontmatter, validate JSON
|
|
- **Content comparison**: Use Bash (diff) — Byte-identical prompt verification
|
|
- **Formatting**: Use Bash (alejandra --check) — No formatting drift
|
|
|
|
---
|
|
|
|
## Execution Strategy
|
|
|
|
### Parallel Execution Waves
|
|
|
|
```
|
|
Wave 1 (Start Immediately — foundation + spike):
|
|
├── Task 1: Capture golden file baseline [quick]
|
|
├── Task 2: TOML feasibility spike with Chiron-Forge [quick]
|
|
├── Task 3: Design canonical agent.toml schema [deep]
|
|
└── Task 4: Research OpenCode file-based agent frontmatter [quick]
|
|
|
|
Wave 2 (After Wave 1 — AGENTS repo migration):
|
|
├── Task 5: Create all 6 agent.toml + system-prompt.md files [unspecified-high]
|
|
├── Task 6: Update AGENTS flake.nix with loadAgents + agentsJson [deep]
|
|
├── Task 7: Create lib/agents.nix in nixpkgs with loadCanonical [deep]
|
|
└── Task 8: Verify backward-compat bridge produces golden file match [quick]
|
|
|
|
Wave 3 (After Wave 2 — renderers + HM modules, MAX PARALLEL):
|
|
├── Task 9: Implement OpenCode renderer in lib/agents.nix [deep]
|
|
├── Task 10: Implement Claude Code renderer in lib/agents.nix [deep]
|
|
├── Task 11: Implement Pi renderer in lib/agents.nix [unspecified-high]
|
|
├── Task 12: Create HM sub-module for OpenCode (agents/opencode.nix) [unspecified-high]
|
|
├── Task 13: Create HM sub-module for Claude Code (agents/claude-code.nix) [unspecified-high]
|
|
├── Task 14: Create HM sub-module for Pi (agents/pi.nix) [unspecified-high]
|
|
├── Task 15: Slim down existing opencode.nix to non-agent config only [quick]
|
|
└── Task 16: Rename mkOpencodeRules to mkCodingRules + backward-compat alias [quick]
|
|
|
|
Wave 4 (After Wave 3 — integration + project-level + cleanup):
|
|
├── Task 17: Add project-level renderForTool lib function [deep]
|
|
├── Task 18: Update nixpkgs flake.nix exports + aggregator imports [quick]
|
|
├── Task 19: Update AGENTS.md documentation [quick]
|
|
├── Task 20: Remove legacy agents.json + prompts/*.txt from AGENTS repo [quick]
|
|
└── Task 21: End-to-end integration test across both repos [unspecified-high]
|
|
|
|
Wave FINAL (After ALL tasks — 4 parallel reviews, then user okay):
|
|
├── 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)
|
|
-> Present results -> Get explicit user okay
|
|
```
|
|
|
|
### Dependency Matrix
|
|
|
|
| Task | Depends On | Blocks | Wave |
|
|
|------|-----------|--------|------|
|
|
| 1 | — | 8, 21 | 1 |
|
|
| 2 | — | 3, 5 | 1 |
|
|
| 3 | 2 | 5, 6, 7 | 1 |
|
|
| 4 | — | 9, 12 | 1 |
|
|
| 5 | 2, 3 | 6, 8, 9, 10, 11 | 2 |
|
|
| 6 | 3, 5 | 8, 17 | 2 |
|
|
| 7 | 3 | 9, 10, 11, 12, 13, 14, 17 | 2 |
|
|
| 8 | 1, 5, 6 | 20 | 2 |
|
|
| 9 | 4, 5, 7 | 12 | 3 |
|
|
| 10 | 5, 7 | 13 | 3 |
|
|
| 11 | 5, 7 | 14 | 3 |
|
|
| 12 | 9 | 18, 21 | 3 |
|
|
| 13 | 10 | 18, 21 | 3 |
|
|
| 14 | 11 | 18, 21 | 3 |
|
|
| 15 | — | 18 | 3 |
|
|
| 16 | — | 18 | 3 |
|
|
| 17 | 6, 7 | 21 | 4 |
|
|
| 18 | 12, 13, 14, 15, 16 | 21 | 4 |
|
|
| 19 | 5 | — | 4 |
|
|
| 20 | 8 | — | 4 |
|
|
| 21 | 1, 12, 13, 14, 17, 18 | F1-F4 | 4 |
|
|
|
|
### Agent Dispatch Summary
|
|
|
|
- **Wave 1**: **4** — T1 → `quick`, T2 → `quick`, T3 → `deep`, T4 → `quick`
|
|
- **Wave 2**: **4** — T5 → `unspecified-high`, T6 → `deep`, T7 → `deep`, T8 → `quick`
|
|
- **Wave 3**: **8** — T9 → `deep`, T10 → `deep`, T11 → `unspecified-high`, T12-T14 → `unspecified-high`, T15-T16 → `quick`
|
|
- **Wave 4**: **5** — T17 → `deep`, T18 → `quick`, T19 → `quick`, T20 → `quick`, T21 → `unspecified-high`
|
|
- **FINAL**: **4** — F1 → `oracle`, F2 → `unspecified-high`, F3 → `unspecified-high`, F4 → `deep`
|
|
|
|
---
|
|
|
|
## TODOs
|
|
|
|
- [x] 1. Capture Golden File Baseline
|
|
|
|
**What to do**:
|
|
- On the machine where home-manager is configured, capture the current rendered OpenCode agent config:
|
|
```bash
|
|
nix eval --json '.#homeConfigurations.sk.config.programs.opencode.settings.agent' | jq --sort-keys . > /tmp/agents-golden.json
|
|
```
|
|
- Also capture the raw agents.json for direct comparison:
|
|
```bash
|
|
jq --sort-keys . /home/m3tam3re/p/AI/AGENTS/agents/agents.json > /tmp/agents-json-golden.json
|
|
```
|
|
- Store both golden files in `.sisyphus/evidence/` for later use by other tasks
|
|
- Note: If home-manager eval isn't available, use direct file comparison as fallback
|
|
|
|
**Must NOT do**:
|
|
- Modify any source files
|
|
- Change agents.json content
|
|
|
|
**Recommended Agent Profile**:
|
|
- **Category**: `quick`
|
|
- **Skills**: []
|
|
|
|
**Parallelization**:
|
|
- **Can Run In Parallel**: YES
|
|
- **Parallel Group**: Wave 1 (with Tasks 2, 3, 4)
|
|
- **Blocks**: Tasks 8, 21
|
|
- **Blocked By**: None
|
|
|
|
**References**:
|
|
- `agents/agents.json` — Current source of truth (173 lines, 6 agents)
|
|
- `modules/home-manager/coding/opencode.nix:148-149` in nixpkgs — Where agents.json gets embedded via `builtins.fromJSON (builtins.readFile ...)`
|
|
|
|
**Acceptance Criteria**:
|
|
|
|
**QA Scenarios (MANDATORY):**
|
|
|
|
```
|
|
Scenario: Golden file captured and parseable
|
|
Tool: Bash
|
|
Preconditions: AGENTS repo at /home/m3tam3re/p/AI/AGENTS
|
|
Steps:
|
|
1. Run: jq --sort-keys . /home/m3tam3re/p/AI/AGENTS/agents/agents.json > .sisyphus/evidence/agents-golden.json
|
|
2. Run: jq 'keys | length' .sisyphus/evidence/agents-golden.json
|
|
3. Assert output is exactly "6" (6 agents)
|
|
4. Run: jq 'keys' .sisyphus/evidence/agents-golden.json
|
|
5. Assert output contains "Chiron (Assistant)", "Chiron Forge (Builder)", "Hermes (Communication)", "Athena (Researcher)", "Apollo (Knowledge Management)", "Calliope (Writer)"
|
|
Expected Result: Golden file exists, contains 6 agents, valid JSON
|
|
Failure Indicators: jq parse error, agent count != 6, missing agent names
|
|
Evidence: .sisyphus/evidence/agents-golden.json
|
|
```
|
|
|
|
**Commit**: NO (evidence only, no source changes)
|
|
|
|
---
|
|
|
|
- [x] 2. TOML Feasibility Spike — Chiron-Forge Permission Matrix
|
|
|
|
**What to do**:
|
|
- Write a test `agent.toml` for Chiron-Forge (the most complex agent — 2 primary modes, 15+ bash permission patterns with globs, wildcards, and special characters)
|
|
- Test it parses correctly with `nix eval --expr 'builtins.fromTOML (builtins.readFile ./test.toml)'`
|
|
- Specifically verify these tricky patterns parse in TOML strings:
|
|
- `"rm -rf *"` (glob with spaces)
|
|
- `"git reset --hard*"` (double-dash + glob)
|
|
- `"git push --force*"` (double-dash + glob)
|
|
- `"git push -f *"` (short flag + glob)
|
|
- `"~/p/**"` (home dir + double glob)
|
|
- `"/run/agenix/**"` (absolute path + double glob)
|
|
- Test the two-level permission schema: simple intent + rules array
|
|
- Write the test file to a temporary location, NOT in agents/ yet
|
|
- If parsing FAILS: document exactly what fails and propose schema workaround
|
|
|
|
**Must NOT do**:
|
|
- Create permanent files in agents/ directory (this is a spike)
|
|
- Modify flake.nix
|
|
|
|
**Recommended Agent Profile**:
|
|
- **Category**: `quick`
|
|
- **Skills**: []
|
|
|
|
**Parallelization**:
|
|
- **Can Run In Parallel**: YES
|
|
- **Parallel Group**: Wave 1 (with Tasks 1, 3, 4)
|
|
- **Blocks**: Tasks 3, 5
|
|
- **Blocked By**: None
|
|
|
|
**References**:
|
|
- `agents/agents.json:40-68` — Chiron Forge's full permission matrix (the most complex agent)
|
|
- `agents/agents.json:1-38` — Chiron's permission matrix (read-only agent with extensive bash allowlist)
|
|
- Nix TOML docs: `builtins.fromTOML` supports TOML 1.0.0 strict (toml11 v4). No datetime, no multi-line inline tables.
|
|
|
|
**Acceptance Criteria**:
|
|
|
|
**QA Scenarios (MANDATORY):**
|
|
|
|
```
|
|
Scenario: TOML parses all permission patterns correctly
|
|
Tool: Bash
|
|
Preconditions: Nix available with builtins.fromTOML
|
|
Steps:
|
|
1. Write test agent.toml with Chiron-Forge's full permission set to /tmp/test-agent.toml
|
|
2. Run: nix eval --expr 'builtins.fromTOML (builtins.readFile /tmp/test-agent.toml)' --json
|
|
3. Pipe output to jq and verify:
|
|
- .name == "chiron-forge"
|
|
- .permissions.bash.intent == "allow"
|
|
- .permissions.bash.rules | length >= 4 (deny rules)
|
|
- .permissions.edit.intent == "allow"
|
|
- .permissions.external_directory.rules | length >= 4
|
|
4. Verify each deny pattern string is preserved exactly (no escaping issues)
|
|
Expected Result: All fields parse, all glob patterns preserved, all special characters intact
|
|
Failure Indicators: Nix eval error, missing fields, mangled glob patterns, escape issues
|
|
Evidence: .sisyphus/evidence/task-2-toml-spike.json
|
|
|
|
Scenario: TOML handles edge cases (empty rules, minimal agent)
|
|
Tool: Bash
|
|
Preconditions: Nix available
|
|
Steps:
|
|
1. Write minimal agent.toml with only name + description to /tmp/test-minimal.toml
|
|
2. Run: nix eval --expr 'builtins.fromTOML (builtins.readFile /tmp/test-minimal.toml)' --json
|
|
3. Assert parse succeeds with only required fields
|
|
Expected Result: Minimal TOML parses without error
|
|
Failure Indicators: Nix eval error on missing optional fields
|
|
Evidence: .sisyphus/evidence/task-2-toml-minimal.json
|
|
```
|
|
|
|
**Commit**: NO (spike only, temporary files)
|
|
|
|
---
|
|
|
|
- [x] 3. Design Canonical agent.toml Schema
|
|
|
|
**What to do**:
|
|
- Based on TOML spike results (Task 2) and research findings, define the final canonical schema
|
|
- Create `agents/SCHEMA.md` documenting the canonical format with:
|
|
- All required fields: `name` (string, kebab-case), `description` (string)
|
|
- All optional fields: `mode`, `tags`, `max_turns`
|
|
- Permission schema: `[permissions.TOOL]` tables with `intent` (allow/deny/ask) + `rules` (array of "pattern:action" strings)
|
|
- Skill references: `skills` array of skill names
|
|
- Context references: `context` array of file paths
|
|
- Rule references: `rules` array of rule paths (e.g. "languages/nix")
|
|
- NO `model` field (model is per-machine via home-manager)
|
|
- NO `prompt` field (prompt lives in system-prompt.md, not in TOML)
|
|
- NO MCP configuration (tool-specific)
|
|
- NO datetime fields (Nix limitation)
|
|
- Schema must be a SUPERSET: renderers silently drop fields they can't map
|
|
- Document per-renderer field support matrix in SCHEMA.md
|
|
|
|
**Must NOT do**:
|
|
- Include model configuration (per-machine concern)
|
|
- Include MCP server config (tool-specific infrastructure)
|
|
- Include hooks (Claude Code exclusive, not canonical)
|
|
- Use datetime TOML types
|
|
- Use multi-line inline tables
|
|
|
|
**Recommended Agent Profile**:
|
|
- **Category**: `deep`
|
|
- **Skills**: []
|
|
|
|
**Parallelization**:
|
|
- **Can Run In Parallel**: YES (but should incorporate Task 2 results if available)
|
|
- **Parallel Group**: Wave 1 (with Tasks 1, 2, 4)
|
|
- **Blocks**: Tasks 5, 6, 7
|
|
- **Blocked By**: Task 2 (TOML feasibility must pass first)
|
|
|
|
**References**:
|
|
- Task 2's TOML spike results — Confirms which TOML patterns work
|
|
- `agents/agents.json` — Current field set to preserve (all 6 agents)
|
|
- Claude Code sub-agents docs — Required frontmatter fields: `name` (kebab-case), `description`
|
|
- OpenCode agent schema — Supports: name, description, mode, model, temperature, top_p, steps, permission[], color, hidden, disable
|
|
- Pi README — No agent schema. Uses AGENTS.md + SYSTEM.md + settings.json
|
|
|
|
**Acceptance Criteria**:
|
|
|
|
**QA Scenarios (MANDATORY):**
|
|
|
|
```
|
|
Scenario: Schema document is complete and internally consistent
|
|
Tool: Bash
|
|
Preconditions: agents/SCHEMA.md created
|
|
Steps:
|
|
1. Read agents/SCHEMA.md
|
|
2. Verify it documents: required fields, optional fields, permission schema, skill references, context references
|
|
3. Verify it explicitly lists: fields NOT included (model, prompt, mcp, hooks, datetime)
|
|
4. Verify it includes a per-renderer support matrix table
|
|
5. Write a sample agent.toml following the schema and parse it with builtins.fromTOML
|
|
Expected Result: Schema is complete, sample TOML parses successfully
|
|
Failure Indicators: Missing field documentation, sample TOML fails to parse
|
|
Evidence: .sisyphus/evidence/task-3-schema-sample.toml
|
|
```
|
|
|
|
**Commit**: YES
|
|
- Message: `docs: add canonical agent.toml schema definition`
|
|
- Files: `agents/SCHEMA.md`
|
|
- Pre-commit: `nix eval --expr 'builtins.fromTOML (builtins.readFile ./evidence-sample.toml)' --json`
|
|
|
|
---
|
|
|
|
- [x] 4. Research OpenCode File-Based Agent Frontmatter
|
|
|
|
**What to do**:
|
|
- Verify OpenCode's `.opencode/agent/*.md` file-based agent format by reading source code or docs
|
|
- Document the exact YAML frontmatter fields supported:
|
|
- Which fields map from canonical agent.toml?
|
|
- What is the permission format in frontmatter?
|
|
- How does `mode: primary | subagent | all` work?
|
|
- What is the default behavior for omitted fields?
|
|
- How does file-based agent discovery interact with config.json `agent` key?
|
|
- Confirm that file-based agents DON'T require `home-manager switch` for prompt changes (key advantage over config.json embedding)
|
|
- Save findings to `.sisyphus/evidence/task-4-opencode-agent-format.md`
|
|
|
|
**Must NOT do**:
|
|
- Modify any files
|
|
- Create agent files yet (that's Task 5)
|
|
|
|
**Recommended Agent Profile**:
|
|
- **Category**: `quick`
|
|
- **Skills**: []
|
|
|
|
**Parallelization**:
|
|
- **Can Run In Parallel**: YES
|
|
- **Parallel Group**: Wave 1 (with Tasks 1, 2, 3)
|
|
- **Blocks**: Tasks 9, 12
|
|
- **Blocked By**: None
|
|
|
|
**References**:
|
|
- OpenCode GitHub: `github.com/sst/opencode` (or `anomalyco/opencode`) — search for agent loading logic
|
|
- OpenCode docs on file-based agents: `.opencode/agent/*.md` with YAML frontmatter
|
|
- Current opencode.nix:148 in nixpkgs — Shows config.json embedding approach (what we're moving away from)
|
|
|
|
**Acceptance Criteria**:
|
|
|
|
**QA Scenarios (MANDATORY):**
|
|
|
|
```
|
|
Scenario: OpenCode file-based agent format documented
|
|
Tool: Bash
|
|
Preconditions: Research complete
|
|
Steps:
|
|
1. Read .sisyphus/evidence/task-4-opencode-agent-format.md
|
|
2. Verify it documents: supported frontmatter fields, permission format, mode values, default behaviors
|
|
3. Verify it confirms or denies: file-based agents don't need home-manager switch
|
|
Expected Result: Complete format documentation with concrete examples
|
|
Failure Indicators: Missing field documentation, unresolved questions about discovery behavior
|
|
Evidence: .sisyphus/evidence/task-4-opencode-agent-format.md
|
|
```
|
|
|
|
**Commit**: NO (research only)
|
|
|
|
- [x] 5. Create All 6 agent.toml + system-prompt.md Files
|
|
|
|
**What to do**:
|
|
- For each of the 6 agents, create `agents/{name}/agent.toml` following the schema from Task 3
|
|
- For each agent, copy (byte-identical!) the system prompt from `prompts/{name}.txt` to `agents/{name}/system-prompt.md`
|
|
- Agent directories to create: `chiron`, `chiron-forge`, `hermes`, `athena`, `apollo`, `calliope`
|
|
- Translate current JSON fields to TOML:
|
|
- `"Chiron (Assistant)"` → `name = "chiron"`, `display_name = "Chiron (Assistant)"`
|
|
- `"mode": "primary"` → `mode = "primary"`
|
|
- `"description": "..."` → `description = "..."`
|
|
- Permission objects → two-level `[permissions.TOOL]` tables
|
|
- Translate OpenCode's nested bash permission objects:
|
|
```json
|
|
"bash": { "*": "ask", "git status*": "allow", ... }
|
|
```
|
|
Into TOML:
|
|
```toml
|
|
[permissions.bash]
|
|
intent = "ask"
|
|
rules = ["git status*:allow", "git log*:allow", ...]
|
|
```
|
|
- Translate external_directory permissions similarly
|
|
- Skills, rules, context references per existing agent capabilities
|
|
- Verify EVERY toml file parses with `builtins.fromTOML`
|
|
|
|
**Must NOT do**:
|
|
- Change prompt content (byte-identical copy only)
|
|
- Include `model` field in agent.toml (per-machine concern)
|
|
- Delete old agents.json or prompts/ yet (Task 20)
|
|
- Add MCP config to agent.toml
|
|
|
|
**Recommended Agent Profile**:
|
|
- **Category**: `unspecified-high`
|
|
- **Skills**: []
|
|
|
|
**Parallelization**:
|
|
- **Can Run In Parallel**: NO (depends on schema from Task 3)
|
|
- **Parallel Group**: Wave 2
|
|
- **Blocks**: Tasks 6, 8, 9, 10, 11, 19
|
|
- **Blocked By**: Tasks 2, 3
|
|
|
|
**References**:
|
|
- `agents/agents.json` — Source data for all 6 agents (173 lines)
|
|
- `prompts/chiron.txt` through `prompts/calliope.txt` — System prompts to copy
|
|
- `agents/SCHEMA.md` (from Task 3) — Canonical schema to follow
|
|
- Task 2 results — Confirmed TOML parsing patterns
|
|
|
|
**Acceptance Criteria**:
|
|
|
|
**QA Scenarios (MANDATORY):**
|
|
|
|
```
|
|
Scenario: All 6 agent.toml files parse without error
|
|
Tool: Bash
|
|
Preconditions: All agents/*/agent.toml created
|
|
Steps:
|
|
1. for f in agents/*/agent.toml; do nix eval --expr "builtins.fromTOML (builtins.readFile ./$f)" --json > /dev/null && echo "OK: $f" || echo "FAIL: $f"; done
|
|
2. Assert all 6 print "OK"
|
|
3. Verify each has required fields: nix eval --expr '(builtins.fromTOML (builtins.readFile ./agents/chiron/agent.toml)).name' → "chiron"
|
|
Expected Result: All 6 TOML files parse, all have name + description
|
|
Failure Indicators: Any nix eval error, missing required fields
|
|
Evidence: .sisyphus/evidence/task-5-toml-parse-all.txt
|
|
|
|
Scenario: System prompts are byte-identical to originals
|
|
Tool: Bash
|
|
Preconditions: All agents/*/system-prompt.md created
|
|
Steps:
|
|
1. diff prompts/chiron.txt agents/chiron/system-prompt.md
|
|
2. diff prompts/chiron-forge.txt agents/chiron-forge/system-prompt.md
|
|
3. diff prompts/hermes.txt agents/hermes/system-prompt.md
|
|
4. diff prompts/athena.txt agents/athena/system-prompt.md
|
|
5. diff prompts/apollo.txt agents/apollo/system-prompt.md
|
|
6. diff prompts/calliope.txt agents/calliope/system-prompt.md
|
|
7. All diffs must exit with code 0 (no differences)
|
|
Expected Result: Zero differences across all 6 files
|
|
Failure Indicators: Any diff showing changes
|
|
Evidence: .sisyphus/evidence/task-5-prompt-diff.txt
|
|
|
|
Scenario: Permission patterns preserved exactly
|
|
Tool: Bash
|
|
Preconditions: agents/chiron-forge/agent.toml exists
|
|
Steps:
|
|
1. nix eval --expr '(builtins.fromTOML (builtins.readFile ./agents/chiron-forge/agent.toml)).permissions.bash.rules' --json
|
|
2. Assert result contains: "rm -rf *:ask", "git reset --hard*:ask", "git push --force*:deny", "git push -f *:deny"
|
|
3. nix eval --expr '(builtins.fromTOML (builtins.readFile ./agents/chiron/agent.toml)).permissions.bash.rules' --json
|
|
4. Assert result contains at least 12 allow rules (git status*, git log*, etc.)
|
|
Expected Result: All glob patterns preserved with correct actions
|
|
Failure Indicators: Missing patterns, wrong action types, escaping issues
|
|
Evidence: .sisyphus/evidence/task-5-permissions.json
|
|
```
|
|
|
|
**Commit**: YES
|
|
- Message: `feat: add canonical agent.toml definitions for all 6 agents`
|
|
- Files: `agents/*/agent.toml`, `agents/*/system-prompt.md`
|
|
- Pre-commit: `for f in agents/*/agent.toml; do nix eval --expr "builtins.fromTOML (builtins.readFile ./$f)" --json > /dev/null; done`
|
|
|
|
---
|
|
|
|
- [x] 6. Update AGENTS flake.nix with loadAgents + agentsJson Bridge
|
|
|
|
**What to do**:
|
|
- Add `lib.loadAgents` function to AGENTS repo's flake.nix:
|
|
- Reads all `agents/*/agent.toml` via `builtins.fromTOML (builtins.readFile ...)`
|
|
- Reads corresponding `system-prompt.md` via `builtins.readFile`
|
|
- Returns an attrset: `{ chiron = { name; description; mode; permissions; ...; systemPrompt = "..."; }; ... }`
|
|
- Discovery: reads `agents/` directory, filters for subdirs containing `agent.toml`
|
|
- Add `lib.agentsJson` backward-compat bridge function:
|
|
- Calls `loadAgents`, transforms back to current agents.json shape
|
|
- Maps canonical permission format back to OpenCode's nested objects
|
|
- Maps `systemPrompt` back to `"prompt": "{file:./prompts/chiron.txt}"` format (or inline)
|
|
- Adds `model` field from a configurable default (since agent.toml has no model)
|
|
- Keep ALL existing exports unchanged: `lib.mkOpencodeSkills`, `packages.skills-runtime`, `devShells.default`
|
|
- `lib` export must be system-independent (no `forAllSystems` wrapper — pure functions)
|
|
|
|
**Must NOT do**:
|
|
- Change mkOpencodeSkills
|
|
- Remove any existing exports
|
|
- Add renderer logic (that goes in nixpkgs)
|
|
- Hardcode machine-specific model assignments
|
|
|
|
**Recommended Agent Profile**:
|
|
- **Category**: `deep`
|
|
- **Skills**: []
|
|
|
|
**Parallelization**:
|
|
- **Can Run In Parallel**: YES (with Task 7)
|
|
- **Parallel Group**: Wave 2
|
|
- **Blocks**: Tasks 8, 17
|
|
- **Blocked By**: Tasks 3, 5
|
|
|
|
**References**:
|
|
- `flake.nix` — Current AGENTS flake (188 lines). Keep structure, add to `lib` section.
|
|
- `flake.nix:52-123` — `lib.mkOpencodeSkills` pattern (linkFarm approach)
|
|
- `agents/agents.json` — Target output shape for agentsJson bridge function
|
|
- `agents/SCHEMA.md` (from Task 3) — Canonical schema definition
|
|
|
|
**Acceptance Criteria**:
|
|
|
|
**QA Scenarios (MANDATORY):**
|
|
|
|
```
|
|
Scenario: loadAgents returns all 6 agents with correct structure
|
|
Tool: Bash
|
|
Preconditions: Task 5 complete, flake.nix updated
|
|
Steps:
|
|
1. nix eval --json '.#lib.loadAgents' | jq 'keys | length'
|
|
2. Assert output is 6
|
|
3. nix eval --json '.#lib.loadAgents' | jq '.chiron.name'
|
|
4. Assert output is "chiron"
|
|
5. nix eval --json '.#lib.loadAgents' | jq '.["chiron-forge"].permissions.bash.intent'
|
|
6. Assert output is "allow"
|
|
Expected Result: 6 agents loaded, all fields present
|
|
Failure Indicators: Eval error, wrong agent count, missing fields
|
|
Evidence: .sisyphus/evidence/task-6-loadagents.json
|
|
|
|
Scenario: agentsJson bridge matches golden file
|
|
Tool: Bash
|
|
Preconditions: Golden file from Task 1 available
|
|
Steps:
|
|
1. nix eval --json '.#lib.agentsJson' | jq --sort-keys . > /tmp/agents-bridge-output.json
|
|
2. diff /tmp/agents-bridge-output.json .sisyphus/evidence/agents-golden.json
|
|
3. Exit code must be 0
|
|
Expected Result: Bridge output is semantically identical to original agents.json
|
|
Failure Indicators: Any diff (key ordering differences are OK if using jq --sort-keys)
|
|
Evidence: .sisyphus/evidence/task-6-bridge-diff.txt
|
|
```
|
|
|
|
**Commit**: YES
|
|
- Message: `feat: export loadAgents and backward-compat agentsJson from flake`
|
|
- Files: `flake.nix`
|
|
- Pre-commit: `nix flake check && nix eval --json '.#lib.loadAgents' > /dev/null`
|
|
|
|
---
|
|
|
|
- [x] 7. Create lib/agents.nix in nixpkgs with loadCanonical
|
|
|
|
**What to do**:
|
|
- Create `/home/m3tam3re/p/NIX/nixpkgs/lib/agents.nix` with:
|
|
- `loadCanonical { agentsInput }` — reads canonical agents from the AGENTS flake input
|
|
- Calls `agentsInput.lib.loadAgents` (from Task 6) to get canonical attrset
|
|
- Returns the canonical attrset (or wraps/validates it)
|
|
- Stub functions for renderers (to be implemented in Tasks 9-11):
|
|
- `renderForOpencode { canonical; modelOverrides ? {}; }` → derivation placeholder
|
|
- `renderForClaudeCode { canonical; modelOverrides ? {}; }` → derivation placeholder
|
|
- `renderForPi { canonical; }` → derivation placeholder
|
|
- `renderForTool { agentsInput; tool; modelOverrides ? {}; }` → dispatcher
|
|
- Wire into `lib/default.nix` alongside existing `ports` and `opencode-rules`
|
|
- Follow existing lib patterns: `{lib}: { ... }` function signature
|
|
|
|
**Must NOT do**:
|
|
- Implement actual renderers yet (stubs only — Tasks 9-11)
|
|
- Import pkgs at lib level (renderers need pkgs, but the interface should accept it as argument)
|
|
- Modify existing lib functions
|
|
|
|
**Recommended Agent Profile**:
|
|
- **Category**: `deep`
|
|
- **Skills**: []
|
|
|
|
**Parallelization**:
|
|
- **Can Run In Parallel**: YES (with Task 6)
|
|
- **Parallel Group**: Wave 2
|
|
- **Blocks**: Tasks 9, 10, 11, 12, 13, 14, 17
|
|
- **Blocked By**: Task 3
|
|
|
|
**References**:
|
|
- `lib/default.nix` in nixpkgs — Current lib exports (ports, opencode-rules). Add agents here.
|
|
- `lib/opencode-rules.nix` in nixpkgs — Pattern reference for lib function structure (116 lines)
|
|
- Task 3 SCHEMA.md — Defines the canonical attrset shape
|
|
|
|
**Acceptance Criteria**:
|
|
|
|
**QA Scenarios (MANDATORY):**
|
|
|
|
```
|
|
Scenario: lib/agents.nix loads and stub functions exist
|
|
Tool: Bash
|
|
Preconditions: lib/agents.nix created, lib/default.nix updated
|
|
Steps:
|
|
1. nix eval --expr '(import ./lib { lib = (import <nixpkgs> {}).lib; }).agents' --json
|
|
2. Assert result contains keys: loadCanonical, renderForOpencode, renderForClaudeCode, renderForPi, renderForTool
|
|
3. nix flake check /home/m3tam3re/p/NIX/nixpkgs
|
|
4. Assert exit code 0
|
|
Expected Result: All stub functions exist, flake check passes
|
|
Failure Indicators: Import error, missing function names, flake check failure
|
|
Evidence: .sisyphus/evidence/task-7-lib-agents.json
|
|
```
|
|
|
|
**Commit**: YES
|
|
- Message: `feat(lib): add agents.nix with loadCanonical and renderer stubs`
|
|
- Files: `lib/agents.nix`, `lib/default.nix`
|
|
- Pre-commit: `nix flake check`
|
|
|
|
---
|
|
|
|
- [x] 8. Verify Backward-Compat Bridge Produces Golden File Match
|
|
|
|
**What to do**:
|
|
- With Tasks 1, 5, 6 complete, run the full backward-compat verification:
|
|
```bash
|
|
nix eval --json '.#lib.agentsJson' | jq --sort-keys . > /tmp/bridge-output.json
|
|
diff /tmp/bridge-output.json .sisyphus/evidence/agents-golden.json
|
|
```
|
|
- If diff shows differences, debug and fix in Task 6's `agentsJson` function
|
|
- This is a GATE: do NOT proceed to Wave 3 until this passes
|
|
- Document any semantic differences that are acceptable (e.g., key ordering)
|
|
|
|
**Must NOT do**:
|
|
- Modify the golden file
|
|
- Accept content differences as "close enough"
|
|
|
|
**Recommended Agent Profile**:
|
|
- **Category**: `quick`
|
|
- **Skills**: []
|
|
|
|
**Parallelization**:
|
|
- **Can Run In Parallel**: NO (gate task)
|
|
- **Parallel Group**: Wave 2 (runs last in wave)
|
|
- **Blocks**: Task 20
|
|
- **Blocked By**: Tasks 1, 5, 6
|
|
|
|
**References**:
|
|
- `.sisyphus/evidence/agents-golden.json` — Golden file from Task 1
|
|
- Task 6's `lib.agentsJson` — Bridge function to verify
|
|
|
|
**Acceptance Criteria**:
|
|
|
|
**QA Scenarios (MANDATORY):**
|
|
|
|
```
|
|
Scenario: Bridge output matches golden file exactly
|
|
Tool: Bash
|
|
Preconditions: Tasks 1, 5, 6 complete
|
|
Steps:
|
|
1. cd /home/m3tam3re/p/AI/AGENTS
|
|
2. nix eval --json '.#lib.agentsJson' | jq --sort-keys . > /tmp/bridge-verify.json
|
|
3. diff /tmp/bridge-verify.json .sisyphus/evidence/agents-golden.json
|
|
4. Assert exit code 0 (zero differences)
|
|
Expected Result: Byte-identical output after jq normalization
|
|
Failure Indicators: Any diff output, non-zero exit code
|
|
Evidence: .sisyphus/evidence/task-8-bridge-verify.txt
|
|
```
|
|
|
|
**Commit**: NO (verification only)
|
|
|
|
- [x] 9. Implement OpenCode Renderer in lib/agents.nix
|
|
|
|
**What to do**:
|
|
- Replace the `renderForOpencode` stub in `lib/agents.nix` with full implementation
|
|
- Renderer produces a derivation containing `.opencode/agent/*.md` files (file-based agents)
|
|
- For each agent in canonical attrset, generate a markdown file with YAML frontmatter:
|
|
- `name`: from canonical `name`
|
|
- `description`: from canonical `description`
|
|
- `mode`: from canonical `mode` (primary/subagent) — MUST set explicitly (OpenCode defaults to "all")
|
|
- `model`: from `modelOverrides.{name}` if present, otherwise omit (let OpenCode use its default)
|
|
- `permission`: translate canonical two-level permissions to OpenCode's rule array format:
|
|
```yaml
|
|
permission:
|
|
- permission: bash
|
|
pattern: "git status*"
|
|
action: allow
|
|
- permission: bash
|
|
pattern: "*"
|
|
action: ask
|
|
```
|
|
- `steps`: from canonical `max_turns` if present
|
|
- Body of markdown = content of `system-prompt.md`
|
|
- Use `pkgs.writeText` or `pkgs.runCommand` to generate each file, then `pkgs.linkFarm` or `pkgs.symlinkJoin` to combine
|
|
- Handle edge case: agent with no permission rules (omit permission key entirely)
|
|
|
|
**Must NOT do**:
|
|
- Embed agents in config.json (use file-based agent path)
|
|
- Include oh-my-opencode.json or plugin config (that stays in opencode.nix)
|
|
- Hard-code model values
|
|
|
|
**Recommended Agent Profile**:
|
|
- **Category**: `deep`
|
|
- **Skills**: []
|
|
|
|
**Parallelization**:
|
|
- **Can Run In Parallel**: YES (with Tasks 10, 11, 15, 16)
|
|
- **Parallel Group**: Wave 3
|
|
- **Blocks**: Task 12
|
|
- **Blocked By**: Tasks 4, 5, 7
|
|
|
|
**References**:
|
|
- Task 4 evidence — OpenCode file-based agent frontmatter format
|
|
- `agents/agents.json` — Current permission format (for output comparison)
|
|
- `lib/agents.nix` stubs from Task 7 — Replace renderForOpencode
|
|
- OpenCode source: agent file discovery logic
|
|
|
|
**Acceptance Criteria**:
|
|
|
|
**QA Scenarios (MANDATORY):**
|
|
|
|
```
|
|
Scenario: Rendered OpenCode agents have correct frontmatter
|
|
Tool: Bash
|
|
Preconditions: Renderer implemented, AGENTS repo with canonical agents
|
|
Steps:
|
|
1. Build rendered output: nix eval --raw '.#lib.x86_64-linux.agents.renderForOpencode { canonical = inputs.agents.lib.loadAgents; }'
|
|
2. List files in rendered output: expect 6 .md files
|
|
3. For chiron.md: extract YAML frontmatter, verify name="chiron", mode="primary", description present
|
|
4. For chiron-forge.md: verify permission rules contain bash deny patterns for "rm -rf *", "git push --force*"
|
|
5. For hermes.md: verify mode="subagent"
|
|
Expected Result: 6 agent files, correct frontmatter, correct permissions
|
|
Failure Indicators: Missing files, wrong mode, missing permissions
|
|
Evidence: .sisyphus/evidence/task-9-opencode-render.txt
|
|
|
|
Scenario: System prompts appear as markdown body
|
|
Tool: Bash
|
|
Preconditions: Rendered output available
|
|
Steps:
|
|
1. Extract body (after frontmatter) from rendered chiron.md
|
|
2. Compare with agents/chiron/system-prompt.md
|
|
3. Assert byte-identical
|
|
Expected Result: Prompt content unchanged through rendering
|
|
Failure Indicators: Any content difference
|
|
Evidence: .sisyphus/evidence/task-9-prompt-body.txt
|
|
```
|
|
|
|
**Commit**: YES (groups with N1)
|
|
- Message: `feat(lib): implement OpenCode renderer in agents.nix`
|
|
- Files: `lib/agents.nix`
|
|
- Pre-commit: `nix flake check`
|
|
|
|
---
|
|
|
|
- [ ] 10. Implement Claude Code Renderer in lib/agents.nix
|
|
|
|
**What to do**:
|
|
- Replace `renderForClaudeCode` stub with full implementation
|
|
- Renderer produces a derivation containing `.claude/agents/*.md` files AND `.claude/settings.json` fragment
|
|
- For each agent, generate markdown with YAML frontmatter:
|
|
- `name`: slugify canonical name to `[a-z0-9-]+` (e.g., "chiron-forge" stays, "Chiron" → "chiron")
|
|
- `description`: from canonical `description` (REQUIRED by Claude Code)
|
|
- `model`: from `modelOverrides.{name}` → map to Claude Code alias (sonnet/opus/haiku) or full ID
|
|
- `tools`: from canonical permissions — collect tool names where intent=allow into allowlist
|
|
- `disallowedTools`: from canonical permissions — collect tool names where intent=deny
|
|
- `permissionMode`: default to "default" unless canonical specifies
|
|
- `maxTurns`: from canonical `max_turns`
|
|
- `skills`: from canonical `skills` array
|
|
- Generate `.claude/settings.json` with permission rules translated to Claude Code DSL:
|
|
- Canonical `bash: { rules: ["git push*:deny"] }` → `permissions.deny: ["Bash(git push*)"]`
|
|
- Canonical `edit: { intent: "allow" }` → `permissions.allow: ["Edit"]`
|
|
- Body of markdown = content of `system-prompt.md`
|
|
- Handle subagent-only agents: Claude Code agents are always subagents (no "primary" mode)
|
|
|
|
**Must NOT do**:
|
|
- Include MCP server config in settings.json
|
|
- Include hooks (Claude Code exclusive concept, not in canonical)
|
|
- Use non-kebab-case names (Claude Code requires [a-z0-9-]+)
|
|
|
|
**Recommended Agent Profile**:
|
|
- **Category**: `deep`
|
|
- **Skills**: []
|
|
|
|
**Parallelization**:
|
|
- **Can Run In Parallel**: YES (with Tasks 9, 11, 15, 16)
|
|
- **Parallel Group**: Wave 3
|
|
- **Blocks**: Task 13
|
|
- **Blocked By**: Tasks 5, 7
|
|
|
|
**References**:
|
|
- Claude Code sub-agents docs (indexed) — Frontmatter fields, tool names, permission syntax
|
|
- Claude Code settings docs (indexed) — Permission rule DSL: `"Bash(git diff *)"`, `"Read(./.env)"`
|
|
- `lib/agents.nix` stubs from Task 7
|
|
- Claude Code tool names: `Bash`, `Read`, `Edit`, `Write`, `Glob`, `Grep`, `WebFetch`, `Agent(type)`, `MCP(server::tool)`
|
|
|
|
**Acceptance Criteria**:
|
|
|
|
**QA Scenarios (MANDATORY):**
|
|
|
|
```
|
|
Scenario: All Claude Code agent files have valid YAML frontmatter
|
|
Tool: Bash
|
|
Preconditions: Renderer implemented
|
|
Steps:
|
|
1. Build rendered output for claude-code
|
|
2. For each .md file in .claude/agents/:
|
|
python3 -c "
|
|
import yaml, sys
|
|
content = open(sys.argv[1]).read()
|
|
parts = content.split('---', 2)
|
|
fm = yaml.safe_load(parts[1])
|
|
assert 'name' in fm, 'Missing name'
|
|
assert 'description' in fm, 'Missing description'
|
|
assert fm['name'].replace('-','').isalnum(), f'Invalid name: {fm[\"name\"]}'
|
|
print(f'OK: {fm[\"name\"]}')
|
|
" file.md
|
|
3. Assert all 6 files pass
|
|
Expected Result: All frontmatter valid, names in kebab-case
|
|
Failure Indicators: YAML parse error, missing required fields, invalid name format
|
|
Evidence: .sisyphus/evidence/task-10-claude-frontmatter.txt
|
|
|
|
Scenario: Permission DSL correctly translated
|
|
Tool: Bash
|
|
Preconditions: Rendered .claude/settings.json exists
|
|
Steps:
|
|
1. Read rendered .claude/settings.json
|
|
2. Verify permissions.deny contains patterns like "Bash(rm -rf *)" for chiron-forge deny rules
|
|
3. Verify permissions.allow contains patterns like "Bash(git status*)" for chiron allow rules
|
|
Expected Result: Permission rules correctly translated to Claude Code DSL
|
|
Failure Indicators: Missing rules, wrong DSL format, lost patterns
|
|
Evidence: .sisyphus/evidence/task-10-claude-permissions.json
|
|
```
|
|
|
|
**Commit**: YES (groups with N1)
|
|
- Message: `feat(lib): implement Claude Code renderer in agents.nix`
|
|
- Files: `lib/agents.nix`
|
|
- Pre-commit: `nix flake check`
|
|
|
|
---
|
|
|
|
- [ ] 11. Implement Pi Renderer in lib/agents.nix
|
|
|
|
**What to do**:
|
|
- Replace `renderForPi` stub with full implementation
|
|
- Pi has NO subagent concept — renderer produces DIFFERENT outputs than OpenCode/Claude Code:
|
|
- `AGENTS.md` — Concatenation of all agent descriptions + primary agent's instructions
|
|
- `~/.pi/agent/SYSTEM.md` or `.pi/SYSTEM.md` — Primary agent's system prompt (replaces Pi's default prompt)
|
|
- `.pi/settings.json` fragment — Optional: tools list, model config
|
|
- Skill symlinks — Pi uses same SKILL.md dirs at `~/.pi/agent/skills/` or `.agents/skills/`
|
|
- Only PRIMARY agents render to SYSTEM.md. Subagent prompts get embedded as sections in AGENTS.md.
|
|
- Generate AGENTS.md with sections per agent:
|
|
```markdown
|
|
# Agent Instructions
|
|
|
|
## Chiron (Assistant)
|
|
Primary assistant for read-only analysis...
|
|
|
|
## Available Specialists
|
|
- Hermes: Work communication (Basecamp, Outlook, Teams)
|
|
- Athena: Work knowledge (Outline wiki)
|
|
...
|
|
```
|
|
- Pi's tools config: `--tools read,bash,edit,write` maps from canonical permissions
|
|
- Handle: Pi has no permission granularity — only tool enable/disable
|
|
|
|
**Must NOT do**:
|
|
- Create agent files (Pi doesn't have them)
|
|
- Try to render subagents as separate entities
|
|
- Include MCP config (Pi uses extensions instead)
|
|
- Create TS extensions (out of scope)
|
|
|
|
**Recommended Agent Profile**:
|
|
- **Category**: `unspecified-high`
|
|
- **Skills**: []
|
|
|
|
**Parallelization**:
|
|
- **Can Run In Parallel**: YES (with Tasks 9, 10, 15, 16)
|
|
- **Parallel Group**: Wave 3
|
|
- **Blocks**: Task 14
|
|
- **Blocked By**: Tasks 5, 7
|
|
|
|
**References**:
|
|
- Pi README (indexed) — AGENTS.md loaded at startup, SYSTEM.md replaces default prompt, APPEND_SYSTEM.md appends
|
|
- Pi README skills section — `~/.pi/agent/skills/`, `.pi/skills/`, `~/.agents/skills/`, `.agents/skills/`
|
|
- Pi README settings — `~/.pi/agent/settings.json` (global), `.pi/settings.json` (project)
|
|
- Pi README tools — `--tools read,bash,edit,write` (default built-in tools)
|
|
|
|
**Acceptance Criteria**:
|
|
|
|
**QA Scenarios (MANDATORY):**
|
|
|
|
```
|
|
Scenario: Pi renderer produces valid AGENTS.md
|
|
Tool: Bash
|
|
Preconditions: Renderer implemented
|
|
Steps:
|
|
1. Build rendered output for pi
|
|
2. Assert AGENTS.md exists in output
|
|
3. Assert AGENTS.md contains "Chiron" and agent descriptions
|
|
4. Assert AGENTS.md contains specialist listing
|
|
5. Verify AGENTS.md is valid Markdown (no TOML/JSON artifacts)
|
|
Expected Result: AGENTS.md exists with readable agent instructions
|
|
Failure Indicators: File missing, contains raw TOML/JSON, empty content
|
|
Evidence: .sisyphus/evidence/task-11-pi-agents-md.txt
|
|
|
|
Scenario: Pi renderer produces valid SYSTEM.md from primary agent
|
|
Tool: Bash
|
|
Preconditions: Rendered output available
|
|
Steps:
|
|
1. Assert SYSTEM.md or .pi/SYSTEM.md exists in output
|
|
2. Content should be the primary agent's system prompt
|
|
3. Verify it matches agents/chiron/system-prompt.md content
|
|
Expected Result: SYSTEM.md exists with primary agent's prompt
|
|
Failure Indicators: Missing file, wrong content, subagent prompt instead
|
|
Evidence: .sisyphus/evidence/task-11-pi-system-md.txt
|
|
```
|
|
|
|
**Commit**: YES (groups with N1)
|
|
- Message: `feat(lib): implement Pi renderer in agents.nix`
|
|
- Files: `lib/agents.nix`
|
|
- Pre-commit: `nix flake check`
|
|
|
|
---
|
|
|
|
- [ ] 12. Create HM Sub-Module for OpenCode (agents/opencode.nix)
|
|
|
|
**What to do**:
|
|
- Create `modules/home-manager/coding/agents/opencode.nix` in nixpkgs
|
|
- Options under `coding.agents.opencode`:
|
|
- `enable` — mkEnableOption
|
|
- `agentsInput` — flake input pointing to AGENTS repo
|
|
- `modelOverrides` — attrset mapping agent name → model string (e.g., `{ chiron = "anthropic/claude-sonnet-4"; }`)
|
|
- Config (mkIf enabled):
|
|
- Call `lib.agents.renderForOpencode { canonical; modelOverrides; }` to get rendered derivation
|
|
- Symlink rendered `.opencode/agent/` dir via `xdg.configFile` or `home.file`
|
|
- Symlink skills via existing `mkOpencodeSkills` (if agentsInput set)
|
|
- Symlink context/ and commands/ from AGENTS input
|
|
- Create `modules/home-manager/coding/agents/default.nix` aggregator importing opencode.nix, claude-code.nix, pi.nix
|
|
- Update `modules/home-manager/coding/default.nix` to import `./agents` subdir
|
|
|
|
**Must NOT do**:
|
|
- Handle oh-my-opencode.json, plugins, formatters (stays in slimmed opencode.nix)
|
|
- Embed agents in config.json (use file-based agents)
|
|
- Include MCP config
|
|
|
|
**Recommended Agent Profile**:
|
|
- **Category**: `unspecified-high`
|
|
- **Skills**: []
|
|
|
|
**Parallelization**:
|
|
- **Can Run In Parallel**: NO (depends on Task 9)
|
|
- **Parallel Group**: Wave 3 (after Task 9)
|
|
- **Blocks**: Tasks 18, 21
|
|
- **Blocked By**: Task 9
|
|
|
|
**References**:
|
|
- `modules/home-manager/coding/opencode.nix` in nixpkgs — Current module to learn from (168 lines)
|
|
- Task 9's renderer — Produces the derivation this module consumes
|
|
- `modules/home-manager/AGENTS.md` in nixpkgs — Module conventions doc
|
|
|
|
**Acceptance Criteria**:
|
|
|
|
**QA Scenarios (MANDATORY):**
|
|
|
|
```
|
|
Scenario: Module options type-check
|
|
Tool: Bash
|
|
Preconditions: Module created
|
|
Steps:
|
|
1. nix flake check /home/m3tam3re/p/NIX/nixpkgs
|
|
2. Assert exit code 0 (no type errors in module options)
|
|
Expected Result: Flake check passes
|
|
Failure Indicators: Type error in options, missing import
|
|
Evidence: .sisyphus/evidence/task-12-flake-check.txt
|
|
```
|
|
|
|
**Commit**: YES (groups with N2)
|
|
- Message: `feat(hm): add OpenCode agent sub-module`
|
|
- Files: `modules/home-manager/coding/agents/opencode.nix`, `modules/home-manager/coding/agents/default.nix`
|
|
- Pre-commit: `nix flake check`
|
|
|
|
---
|
|
|
|
- [ ] 13. Create HM Sub-Module for Claude Code (agents/claude-code.nix)
|
|
|
|
**What to do**:
|
|
- Create `modules/home-manager/coding/agents/claude-code.nix` in nixpkgs
|
|
- Options under `coding.agents.claude-code`:
|
|
- `enable` — mkEnableOption
|
|
- `agentsInput` — flake input pointing to AGENTS repo
|
|
- `modelOverrides` — attrset mapping agent name → model alias or ID
|
|
- Config (mkIf enabled):
|
|
- Call `lib.agents.renderForClaudeCode { canonical; modelOverrides; }` to get rendered derivation
|
|
- Symlink rendered `.claude/agents/` via `home.file`
|
|
- Generate `.claude/settings.json` with rendered permission rules
|
|
- Symlink skills from AGENTS repo to `~/.claude/skills/` (if skills exist)
|
|
- Handle: Claude Code's `CLAUDE.md` — optionally generate from agent instructions
|
|
|
|
**Must NOT do**:
|
|
- Manage Claude Code's MCP config (.claude.json)
|
|
- Configure Claude Code API keys or auth
|
|
- Include hooks in settings.json
|
|
|
|
**Recommended Agent Profile**:
|
|
- **Category**: `unspecified-high`
|
|
- **Skills**: []
|
|
|
|
**Parallelization**:
|
|
- **Can Run In Parallel**: NO (depends on Task 10)
|
|
- **Parallel Group**: Wave 3 (after Task 10)
|
|
- **Blocks**: Tasks 18, 21
|
|
- **Blocked By**: Task 10
|
|
|
|
**References**:
|
|
- Claude Code settings docs (indexed) — `.claude/` directory structure, settings.json scopes
|
|
- Task 10's renderer — Produces the derivation this module consumes
|
|
|
|
**Acceptance Criteria**:
|
|
|
|
**QA Scenarios (MANDATORY):**
|
|
|
|
```
|
|
Scenario: Module type-checks and creates expected file paths
|
|
Tool: Bash
|
|
Preconditions: Module created
|
|
Steps:
|
|
1. nix flake check /home/m3tam3re/p/NIX/nixpkgs
|
|
2. Assert exit code 0
|
|
Expected Result: Flake check passes
|
|
Failure Indicators: Type error, missing import
|
|
Evidence: .sisyphus/evidence/task-13-flake-check.txt
|
|
```
|
|
|
|
**Commit**: YES (groups with N2)
|
|
- Message: `feat(hm): add Claude Code agent sub-module`
|
|
- Files: `modules/home-manager/coding/agents/claude-code.nix`
|
|
- Pre-commit: `nix flake check`
|
|
|
|
---
|
|
|
|
- [ ] 14. Create HM Sub-Module for Pi (agents/pi.nix)
|
|
|
|
**What to do**:
|
|
- Create `modules/home-manager/coding/agents/pi.nix` in nixpkgs
|
|
- Options under `coding.agents.pi`:
|
|
- `enable` — mkEnableOption
|
|
- `agentsInput` — flake input pointing to AGENTS repo
|
|
- Config (mkIf enabled):
|
|
- Call `lib.agents.renderForPi { canonical; }` to get rendered derivation
|
|
- Place AGENTS.md at `~/.pi/agent/AGENTS.md` via `home.file`
|
|
- Place SYSTEM.md at `~/.pi/agent/SYSTEM.md` via `home.file`
|
|
- Symlink skills from AGENTS repo to `~/.pi/agent/skills/`
|
|
- Optionally symlink prompts from AGENTS repo to `~/.pi/agent/prompts/` (Pi's prompt templates)
|
|
|
|
**Must NOT do**:
|
|
- Create fake agent files (Pi has no subagents)
|
|
- Configure Pi extensions (TypeScript, out of scope)
|
|
- Manage Pi's package system
|
|
|
|
**Recommended Agent Profile**:
|
|
- **Category**: `unspecified-high`
|
|
- **Skills**: []
|
|
|
|
**Parallelization**:
|
|
- **Can Run In Parallel**: NO (depends on Task 11)
|
|
- **Parallel Group**: Wave 3 (after Task 11)
|
|
- **Blocks**: Tasks 18, 21
|
|
- **Blocked By**: Task 11
|
|
|
|
**References**:
|
|
- Pi README (indexed) — `~/.pi/agent/` directory structure, skill paths, prompt template paths
|
|
- Task 11's renderer — Produces the derivation this module consumes
|
|
|
|
**Acceptance Criteria**:
|
|
|
|
**QA Scenarios (MANDATORY):**
|
|
|
|
```
|
|
Scenario: Module type-checks
|
|
Tool: Bash
|
|
Preconditions: Module created
|
|
Steps:
|
|
1. nix flake check /home/m3tam3re/p/NIX/nixpkgs
|
|
2. Assert exit code 0
|
|
Expected Result: Flake check passes
|
|
Failure Indicators: Type error, missing import
|
|
Evidence: .sisyphus/evidence/task-14-flake-check.txt
|
|
```
|
|
|
|
**Commit**: YES (groups with N2)
|
|
- Message: `feat(hm): add Pi agent sub-module`
|
|
- Files: `modules/home-manager/coding/agents/pi.nix`
|
|
- Pre-commit: `nix flake check`
|
|
|
|
---
|
|
|
|
- [ ] 15. Slim Down opencode.nix to Non-Agent Config Only
|
|
|
|
**What to do**:
|
|
- Edit existing `modules/home-manager/coding/opencode.nix` in nixpkgs
|
|
- REMOVE: `agentsInput` option (moved to agents/opencode.nix)
|
|
- REMOVE: `externalSkills` option (moved to agents/opencode.nix)
|
|
- REMOVE: Skills linkFarm generation (moved to agents/opencode.nix)
|
|
- REMOVE: Context/commands/prompts symlinks (moved to agents/opencode.nix)
|
|
- REMOVE: agents.json embedding (`builtins.fromJSON (builtins.readFile ...)`) (replaced by file-based agents)
|
|
- KEEP: `programs.opencode.enable` + `enableMcpIntegration`
|
|
- KEEP: `programs.opencode.settings` with theme, formatter, plugin array
|
|
- KEEP: `ohMyOpencodeSettings` → `oh-my-opencode.json` generation
|
|
- KEEP: `extraSettings` for provider/machine-specific config
|
|
- KEEP: `extraPlugins`
|
|
- Result: opencode.nix handles ONLY tool-specific, non-agent config
|
|
|
|
**Must NOT do**:
|
|
- Delete opencode.nix entirely (it still handles non-agent concerns)
|
|
- Move oh-my-opencode.json to agents module
|
|
- Change option names that other configs depend on (check consumers first)
|
|
|
|
**Recommended Agent Profile**:
|
|
- **Category**: `quick`
|
|
- **Skills**: []
|
|
|
|
**Parallelization**:
|
|
- **Can Run In Parallel**: YES (with Tasks 9-14, 16)
|
|
- **Parallel Group**: Wave 3
|
|
- **Blocks**: Task 18
|
|
- **Blocked By**: None (but coordinate with Task 12 for import order)
|
|
|
|
**References**:
|
|
- `modules/home-manager/coding/opencode.nix` in nixpkgs — Current module (168 lines, will shrink to ~70)
|
|
- Task 12 — New agents/opencode.nix takes over agent concerns
|
|
|
|
**Acceptance Criteria**:
|
|
|
|
**QA Scenarios (MANDATORY):**
|
|
|
|
```
|
|
Scenario: Slimmed opencode.nix still manages non-agent config
|
|
Tool: Bash
|
|
Preconditions: opencode.nix edited
|
|
Steps:
|
|
1. Verify opencode.nix still has: ohMyOpencodeSettings, extraSettings, extraPlugins options
|
|
2. Verify opencode.nix does NOT have: agentsInput, externalSkills options
|
|
3. nix flake check /home/m3tam3re/p/NIX/nixpkgs
|
|
4. Assert exit code 0
|
|
Expected Result: Module compiles, non-agent options preserved, agent options removed
|
|
Failure Indicators: Missing options that should stay, leftover agent options
|
|
Evidence: .sisyphus/evidence/task-15-opencode-slim.txt
|
|
```
|
|
|
|
**Commit**: YES (groups with N3)
|
|
- Message: `refactor(hm): slim opencode.nix to non-agent config only`
|
|
- Files: `modules/home-manager/coding/opencode.nix`
|
|
- Pre-commit: `nix flake check`
|
|
|
|
---
|
|
|
|
- [ ] 16. Rename mkOpencodeRules to mkCodingRules with Backward-Compat Alias
|
|
|
|
**What to do**:
|
|
- In `lib/opencode-rules.nix`: rename the main function to `mkCodingRules`
|
|
- Add backward-compat alias: `mkOpencodeRules = builtins.trace "m3ta-nixpkgs: mkOpencodeRules is deprecated, use mkCodingRules" mkCodingRules;`
|
|
- Rename file: `lib/opencode-rules.nix` → `lib/coding-rules.nix`
|
|
- Update `lib/default.nix`: expose both `coding-rules.mkCodingRules` and `opencode-rules.mkOpencodeRules` (alias)
|
|
- For now, the function body stays identical — tool-agnostic rule rendering is a future enhancement
|
|
|
|
**Must NOT do**:
|
|
- Change the function's behavior or output
|
|
- Remove the old name entirely (backward compat)
|
|
- Add multi-tool rendering logic yet
|
|
|
|
**Recommended Agent Profile**:
|
|
- **Category**: `quick`
|
|
- **Skills**: []
|
|
|
|
**Parallelization**:
|
|
- **Can Run In Parallel**: YES (with Tasks 9-15)
|
|
- **Parallel Group**: Wave 3
|
|
- **Blocks**: Task 18
|
|
- **Blocked By**: None
|
|
|
|
**References**:
|
|
- `lib/opencode-rules.nix` in nixpkgs — Current file (116 lines)
|
|
- `lib/default.nix` in nixpkgs — Current exports
|
|
|
|
**Acceptance Criteria**:
|
|
|
|
**QA Scenarios (MANDATORY):**
|
|
|
|
```
|
|
Scenario: Both old and new names work
|
|
Tool: Bash
|
|
Preconditions: Rename complete
|
|
Steps:
|
|
1. nix eval --expr '(import ./lib { lib = (import <nixpkgs> {}).lib; }).coding-rules.mkCodingRules' --json
|
|
2. Assert function exists (no error)
|
|
3. nix eval --expr '(import ./lib { lib = (import <nixpkgs> {}).lib; }).opencode-rules.mkOpencodeRules' --json
|
|
4. Assert function exists (backward compat, may show deprecation trace)
|
|
Expected Result: Both names resolve to the same function
|
|
Failure Indicators: Either name fails, function behavior changed
|
|
Evidence: .sisyphus/evidence/task-16-rules-rename.txt
|
|
```
|
|
|
|
**Commit**: YES (groups with N5)
|
|
- Message: `refactor(lib): rename mkOpencodeRules to mkCodingRules with compat alias`
|
|
- Files: `lib/coding-rules.nix`, `lib/default.nix`
|
|
- Pre-commit: `nix flake check`
|
|
|
|
- [ ] 17. Add Project-Level renderForTool Lib Function
|
|
|
|
**What to do**:
|
|
- Implement `renderForTool` dispatcher in `lib/agents.nix`:
|
|
```nix
|
|
renderForTool = { pkgs, agentsInput, tool, modelOverrides ? {} }:
|
|
let
|
|
canonical = agentsInput.lib.loadAgents;
|
|
renderers = {
|
|
opencode = renderForOpencode { inherit pkgs canonical modelOverrides; };
|
|
claude-code = renderForClaudeCode { inherit pkgs canonical modelOverrides; };
|
|
pi = renderForPi { inherit pkgs canonical; };
|
|
};
|
|
in renderers.${tool} or (throw "Unknown tool: ${tool}");
|
|
```
|
|
- Add `shellHookForTool` helper that generates a shellHook placing rendered files in project dir:
|
|
- For OpenCode: symlinks `.opencode/agent/` → rendered derivation
|
|
- For Claude Code: symlinks `.claude/agents/` and `.claude/settings.json` → rendered
|
|
- For Pi: symlinks `.pi/SYSTEM.md` and `AGENTS.md` → rendered
|
|
- All shellHooks add appropriate entries to `.gitignore` if not already present
|
|
- Export via `lib.agents.renderForTool` and `lib.agents.shellHookForTool`
|
|
- Usage in project flake.nix:
|
|
```nix
|
|
devShells.default = pkgs.mkShell {
|
|
shellHook = m3taLib.agents.shellHookForTool {
|
|
inherit pkgs;
|
|
agentsInput = inputs.agents;
|
|
tool = "opencode";
|
|
modelOverrides = { chiron = "anthropic/claude-sonnet-4"; };
|
|
};
|
|
};
|
|
```
|
|
|
|
**Must NOT do**:
|
|
- Write files imperatively (use symlinks to Nix store paths)
|
|
- Assume tool from environment (require explicit `tool` argument)
|
|
|
|
**Recommended Agent Profile**:
|
|
- **Category**: `deep`
|
|
- **Skills**: []
|
|
|
|
**Parallelization**:
|
|
- **Can Run In Parallel**: NO
|
|
- **Parallel Group**: Wave 4
|
|
- **Blocks**: Task 21
|
|
- **Blocked By**: Tasks 6, 7 (and implicitly 9-11)
|
|
|
|
**References**:
|
|
- `lib/opencode-rules.nix:106-114` in nixpkgs — shellHook pattern reference (ln -sfn + cat > file)
|
|
- Task 9-11 renderers — Functions this dispatcher calls
|
|
|
|
**Acceptance Criteria**:
|
|
|
|
**QA Scenarios (MANDATORY):**
|
|
|
|
```
|
|
Scenario: renderForTool dispatches correctly
|
|
Tool: Bash
|
|
Preconditions: All renderers implemented
|
|
Steps:
|
|
1. nix eval --raw '.#lib.x86_64-linux.agents.renderForTool { pkgs = import <nixpkgs> {}; agentsInput = inputs.agents; tool = "opencode"; }'
|
|
2. Assert output is a valid store path
|
|
3. List contents — expect .opencode/agent/*.md files
|
|
4. Repeat for tool = "claude-code" — expect .claude/agents/*.md
|
|
5. Repeat for tool = "pi" — expect AGENTS.md + SYSTEM.md
|
|
Expected Result: Each tool produces correct output structure
|
|
Failure Indicators: Eval error, wrong output structure, unknown tool error
|
|
Evidence: .sisyphus/evidence/task-17-renderForTool.txt
|
|
```
|
|
|
|
**Commit**: YES (groups with N4)
|
|
- Message: `feat(lib): add project-level renderForTool function`
|
|
- Files: `lib/agents.nix`
|
|
- Pre-commit: `nix flake check`
|
|
|
|
---
|
|
|
|
- [ ] 18. Update nixpkgs flake.nix Exports + Aggregator Imports
|
|
|
|
**What to do**:
|
|
- Update `modules/home-manager/coding/default.nix` to import `./agents` subdir:
|
|
```nix
|
|
imports = [
|
|
./editors.nix
|
|
./opencode.nix
|
|
./agents
|
|
];
|
|
```
|
|
- Update `flake.nix` homeManagerModules exports:
|
|
- Keep: `default`, `ports`, `zellij-ps`
|
|
- Keep: `opencode` (slimmed version)
|
|
- Add: `agents` pointing to `./modules/home-manager/coding/agents`
|
|
- Remove or deprecate old `opencode` if fully replaced
|
|
- Update `lib/default.nix` to export agents module:
|
|
```nix
|
|
agents = import ./agents.nix { inherit lib; };
|
|
coding-rules = import ./coding-rules.nix { inherit lib; };
|
|
opencode-rules = import ./coding-rules.nix { inherit lib; }; # backward compat
|
|
```
|
|
- Run `nix fmt` (alejandra) on all changed files
|
|
- Run `nix flake check`
|
|
|
|
**Must NOT do**:
|
|
- Remove `opencode` export without backward compat
|
|
- Change export names that external configs depend on
|
|
|
|
**Recommended Agent Profile**:
|
|
- **Category**: `quick`
|
|
- **Skills**: []
|
|
|
|
**Parallelization**:
|
|
- **Can Run In Parallel**: NO (depends on all Wave 3 tasks)
|
|
- **Parallel Group**: Wave 4
|
|
- **Blocks**: Task 21
|
|
- **Blocked By**: Tasks 12, 13, 14, 15, 16
|
|
|
|
**References**:
|
|
- `flake.nix` in nixpkgs — Current exports (lines 78-83)
|
|
- `modules/home-manager/coding/default.nix` — Current aggregator
|
|
- `lib/default.nix` — Current lib exports
|
|
|
|
**Acceptance Criteria**:
|
|
|
|
**QA Scenarios (MANDATORY):**
|
|
|
|
```
|
|
Scenario: All exports resolve without error
|
|
Tool: Bash
|
|
Preconditions: All modules and lib functions created
|
|
Steps:
|
|
1. nix flake check /home/m3tam3re/p/NIX/nixpkgs
|
|
2. nix eval '.#homeManagerModules' --json | jq 'keys'
|
|
3. Assert keys include: "default", "opencode", "agents", "ports", "zellij-ps"
|
|
4. nix fmt --check /home/m3tam3re/p/NIX/nixpkgs
|
|
5. Assert no formatting changes needed
|
|
Expected Result: All exports work, formatting clean
|
|
Failure Indicators: Missing export, eval error, formatting drift
|
|
Evidence: .sisyphus/evidence/task-18-exports.txt
|
|
```
|
|
|
|
**Commit**: YES (groups with N6)
|
|
- Message: `chore: update flake exports and aggregator imports`
|
|
- Files: `flake.nix`, `modules/home-manager/coding/default.nix`, `lib/default.nix`
|
|
- Pre-commit: `nix flake check && nix fmt --check`
|
|
|
|
---
|
|
|
|
- [ ] 19. Update AGENTS.md Documentation
|
|
|
|
**What to do**:
|
|
- Update `/home/m3tam3re/p/AI/AGENTS/AGENTS.md` to reflect new directory structure
|
|
- Document:
|
|
- New `agents/{name}/agent.toml` + `system-prompt.md` structure
|
|
- The canonical TOML schema (reference SCHEMA.md)
|
|
- How renderers work (live in nixpkgs, not here)
|
|
- How to add a new agent
|
|
- How project-level usage works (flake.nix + direnv)
|
|
- Backward-compat bridge (`lib.agentsJson`) — note as temporary
|
|
- Update directory tree diagram
|
|
- Remove references to `agents/agents.json` as canonical source
|
|
- Keep references to skills/, rules/, context/, commands/ unchanged
|
|
|
|
**Must NOT do**:
|
|
- Create README.md (update existing AGENTS.md)
|
|
- Document nixpkgs internals (that's nixpkgs's AGENTS.md responsibility)
|
|
|
|
**Recommended Agent Profile**:
|
|
- **Category**: `quick`
|
|
- **Skills**: []
|
|
|
|
**Parallelization**:
|
|
- **Can Run In Parallel**: YES (with Tasks 17, 18, 20)
|
|
- **Parallel Group**: Wave 4
|
|
- **Blocks**: None
|
|
- **Blocked By**: Task 5
|
|
|
|
**References**:
|
|
- `/home/m3tam3re/p/AI/AGENTS/AGENTS.md` — Current documentation
|
|
- Task 3's SCHEMA.md — Schema to reference
|
|
|
|
**Acceptance Criteria**:
|
|
|
|
**QA Scenarios (MANDATORY):**
|
|
|
|
```
|
|
Scenario: AGENTS.md reflects new structure
|
|
Tool: Bash
|
|
Preconditions: AGENTS.md updated
|
|
Steps:
|
|
1. grep "agent.toml" AGENTS.md — assert found
|
|
2. grep "system-prompt.md" AGENTS.md — assert found
|
|
3. grep "agents.json" AGENTS.md — should NOT appear as "canonical" or "source of truth"
|
|
Expected Result: Documentation reflects canonical TOML format
|
|
Failure Indicators: References to old agents.json as primary, missing new structure docs
|
|
Evidence: .sisyphus/evidence/task-19-docs-check.txt
|
|
```
|
|
|
|
**Commit**: YES (groups with A4)
|
|
- Message: `docs: update AGENTS.md for canonical agent format`
|
|
- Files: `AGENTS.md`
|
|
|
|
---
|
|
|
|
- [ ] 20. Remove Legacy agents.json + prompts/*.txt from AGENTS Repo
|
|
|
|
**What to do**:
|
|
- ONLY after Task 8 confirms backward-compat bridge works
|
|
- ONLY after nixpkgs modules consume new canonical format (Tasks 12-14 complete)
|
|
- Delete `agents/agents.json`
|
|
- Delete `prompts/chiron.txt`, `prompts/chiron-forge.txt`, `prompts/hermes.txt`, `prompts/athena.txt`, `prompts/apollo.txt`, `prompts/calliope.txt`
|
|
- Delete `prompts/` directory if empty
|
|
- Remove `lib.agentsJson` backward-compat function from flake.nix
|
|
- Verify `nix flake check` still passes after removal
|
|
|
|
**Must NOT do**:
|
|
- Remove before nixpkgs consumers are updated
|
|
- Remove system-prompt.md files (those are the NEW canonical prompts)
|
|
- Remove skills/, rules/, context/, commands/
|
|
|
|
**Recommended Agent Profile**:
|
|
- **Category**: `quick`
|
|
- **Skills**: []
|
|
|
|
**Parallelization**:
|
|
- **Can Run In Parallel**: YES (with Tasks 17, 18, 19)
|
|
- **Parallel Group**: Wave 4
|
|
- **Blocks**: None
|
|
- **Blocked By**: Task 8 (golden file match confirmed)
|
|
|
|
**References**:
|
|
- `agents/agents.json` — File to delete
|
|
- `prompts/*.txt` — Files to delete
|
|
|
|
**Acceptance Criteria**:
|
|
|
|
**QA Scenarios (MANDATORY):**
|
|
|
|
```
|
|
Scenario: Legacy files removed, canonical files remain
|
|
Tool: Bash
|
|
Preconditions: Tasks 8, 12-14 confirmed complete
|
|
Steps:
|
|
1. test ! -f agents/agents.json — assert file does NOT exist
|
|
2. test ! -d prompts/ — assert directory does NOT exist (or is empty)
|
|
3. for d in agents/chiron agents/chiron-forge agents/hermes agents/athena agents/apollo agents/calliope; do
|
|
test -f "$d/agent.toml" && test -f "$d/system-prompt.md" && echo "OK: $d"
|
|
done
|
|
4. Assert all 6 directories have both files
|
|
5. nix flake check — assert passes
|
|
Expected Result: Legacy removed, canonical intact, flake passes
|
|
Failure Indicators: Legacy files still present, canonical files missing, flake error
|
|
Evidence: .sisyphus/evidence/task-20-cleanup.txt
|
|
```
|
|
|
|
**Commit**: YES (groups with A3)
|
|
- Message: `chore: remove legacy agents.json and prompts/*.txt`
|
|
- Files: `agents/agents.json` (deleted), `prompts/*.txt` (deleted), `flake.nix` (remove agentsJson)
|
|
|
|
---
|
|
|
|
- [ ] 21. End-to-End Integration Test Across Both Repos
|
|
|
|
**What to do**:
|
|
- Full cross-repo integration verification:
|
|
1. In AGENTS repo: `nix eval --json '.#lib.loadAgents'` → verify 6 agents with all fields
|
|
2. In nixpkgs: simulate home-manager eval with agents input:
|
|
- OpenCode: rendered agents dir contains 6 .md files with correct frontmatter
|
|
- Claude Code: rendered .claude/agents/ contains 6 .md files with valid YAML + required fields
|
|
- Pi: rendered output contains AGENTS.md + SYSTEM.md
|
|
3. Project-level: test `renderForTool` for each tool
|
|
4. Skills: verify `mkOpencodeSkills` still produces correct output
|
|
5. Formatting: `nix fmt --check` on both repos
|
|
6. Flake checks: `nix flake check` on both repos
|
|
- Document all results in evidence files
|
|
|
|
**Must NOT do**:
|
|
- Modify any source files (verification only)
|
|
- Skip any tool's verification
|
|
|
|
**Recommended Agent Profile**:
|
|
- **Category**: `unspecified-high`
|
|
- **Skills**: []
|
|
|
|
**Parallelization**:
|
|
- **Can Run In Parallel**: NO (integration gate)
|
|
- **Parallel Group**: Wave 4 (runs last)
|
|
- **Blocks**: F1-F4
|
|
- **Blocked By**: Tasks 1, 12, 13, 14, 17, 18
|
|
|
|
**References**:
|
|
- All previous task evidence files
|
|
- Both repo flake.nix files
|
|
|
|
**Acceptance Criteria**:
|
|
|
|
**QA Scenarios (MANDATORY):**
|
|
|
|
```
|
|
Scenario: Full pipeline works end-to-end
|
|
Tool: Bash
|
|
Preconditions: All tasks 1-20 complete
|
|
Steps:
|
|
1. cd /home/m3tam3re/p/AI/AGENTS && nix flake check && echo "AGENTS: OK"
|
|
2. cd /home/m3tam3re/p/NIX/nixpkgs && nix flake check && echo "nixpkgs: OK"
|
|
3. nix eval --json '/home/m3tam3re/p/AI/AGENTS#lib.loadAgents' | jq 'keys | length' — assert 6
|
|
4. Test each renderer produces output without error
|
|
5. nix fmt --check /home/m3tam3re/p/AI/AGENTS — assert clean
|
|
6. nix fmt --check /home/m3tam3re/p/NIX/nixpkgs — assert clean
|
|
Expected Result: Both repos pass all checks, all renderers produce output
|
|
Failure Indicators: Any flake check failure, renderer error, format drift
|
|
Evidence: .sisyphus/evidence/task-21-e2e.txt
|
|
|
|
Scenario: Skills composition unchanged
|
|
Tool: Bash
|
|
Preconditions: mkOpencodeSkills not modified
|
|
Steps:
|
|
1. nix eval --raw '/home/m3tam3re/p/AI/AGENTS#lib.mkOpencodeSkills { pkgs = import <nixpkgs> {}; customSkills = ./skills; }'
|
|
2. List contents of output directory
|
|
3. Assert contains all active skill directories
|
|
Expected Result: Skills output identical to before migration
|
|
Failure Indicators: Missing skills, broken linkFarm
|
|
Evidence: .sisyphus/evidence/task-21-skills.txt
|
|
```
|
|
|
|
**Commit**: NO (verification only)
|
|
|
|
---
|
|
|
|
## Final Verification Wave (MANDATORY — after ALL implementation tasks)
|
|
|
|
> 4 review agents run in PARALLEL. ALL must APPROVE. Present consolidated results to user and get explicit "okay" before completing.
|
|
>
|
|
> **Do NOT auto-proceed after verification. Wait for user's explicit approval before marking work complete.**
|
|
|
|
- [ ] F1. **Plan Compliance Audit** — `oracle`
|
|
Read the plan end-to-end. For each "Must Have": verify implementation exists (read file, nix eval, diff). For each "Must NOT Have": search codebase for forbidden patterns — reject with file:line if found. Check evidence files exist in .sisyphus/evidence/. Compare deliverables against plan.
|
|
Output: `Must Have [N/N] | Must NOT Have [N/N] | Tasks [N/N] | VERDICT: APPROVE/REJECT`
|
|
|
|
- [ ] F2. **Code Quality Review** — `unspecified-high`
|
|
Run `nix flake check` on both repos. Run `nix fmt --check` (alejandra). Review all .nix files for: unused variables, hardcoded paths, missing mkIf guards, type errors. Check TOML files parse without error. Verify no AI slop: no excessive comments, no placeholder values, no TODO markers in production code.
|
|
Output: `Flake Check [PASS/FAIL] | Format [PASS/FAIL] | Nix Quality [N clean/N issues] | TOML Parse [N/N] | VERDICT`
|
|
|
|
- [ ] F3. **Real Manual QA** — `unspecified-high`
|
|
Execute EVERY QA scenario from EVERY task. Capture evidence. Test cross-task integration: AGENTS repo `lib.loadAgents` → nixpkgs `loadCanonical` → each renderer → home-manager module output. Test edge cases: agent with many permission rules, agent with minimal config, model override. Save to `.sisyphus/evidence/final-qa/`.
|
|
Output: `Scenarios [N/N pass] | Integration [N/N] | Edge Cases [N tested] | VERDICT`
|
|
|
|
- [ ] F4. **Scope Fidelity Check** — `deep`
|
|
For each task: read "What to do", read actual changes. Verify 1:1 — everything in spec was built (no missing), nothing beyond spec was built (no creep). Check "Must NOT do" compliance. Detect: skills/rules changes (forbidden), MCP in agent.toml (forbidden), Codex/Aider renderers (forbidden), prompt content changes (forbidden). Flag unaccounted changes.
|
|
Output: `Tasks [N/N compliant] | Scope [CLEAN/N issues] | Forbidden Patterns [CLEAN/N found] | VERDICT`
|
|
|
|
---
|
|
|
|
## Commit Strategy
|
|
|
|
### AGENTS Repo
|
|
- **Commit A1**: `feat: add canonical agent.toml definitions for all 6 agents` — agents/*/agent.toml + system-prompt.md
|
|
- **Commit A2**: `feat: export loadAgents and backward-compat agentsJson from flake` — flake.nix updates
|
|
- **Commit A3** (after nixpkgs consuming): `chore: remove legacy agents.json and prompts/*.txt`
|
|
- **Commit A4**: `docs: update AGENTS.md for canonical agent format`
|
|
|
|
### m3ta-nixpkgs
|
|
- **Commit N1**: `feat(lib): add agents.nix with loadCanonical and 3 tool renderers`
|
|
- **Commit N2**: `feat(hm): add per-tool agent HM sub-modules (opencode, claude-code, pi)`
|
|
- **Commit N3**: `refactor(hm): slim opencode.nix to non-agent config only`
|
|
- **Commit N4**: `feat(lib): add project-level renderForTool function`
|
|
- **Commit N5**: `refactor(lib): rename mkOpencodeRules to mkCodingRules with compat alias`
|
|
- **Commit N6**: `chore: update flake exports and aggregator imports`
|
|
|
|
---
|
|
|
|
## Success Criteria
|
|
|
|
### Verification Commands
|
|
```bash
|
|
# AGENTS repo: all TOML files parse
|
|
for f in agents/*/agent.toml; do nix eval --expr "builtins.fromTOML (builtins.readFile ./$f)" --json > /dev/null; done
|
|
|
|
# AGENTS repo: backward compat bridge
|
|
diff <(nix eval --json '.#lib.x86_64-linux.agentsJson' | jq --sort-keys .) /tmp/agents-golden.json
|
|
|
|
# AGENTS repo: prompts unchanged
|
|
for agent in chiron chiron-forge hermes athena apollo calliope; do diff "prompts/$agent.txt" "agents/$agent/system-prompt.md"; done
|
|
|
|
# nixpkgs: flake check
|
|
nix flake check /home/m3tam3re/p/NIX/nixpkgs
|
|
|
|
# nixpkgs: formatting
|
|
nix fmt --check /home/m3tam3re/p/NIX/nixpkgs
|
|
|
|
# nixpkgs: OpenCode golden file match
|
|
diff <(nix eval --json '.#homeConfigurations.sk.config.xdg.configFile."opencode/agents"' | jq --sort-keys .) /tmp/opencode-agents-golden.json
|
|
```
|
|
|
|
### Final Checklist
|
|
- [ ] All 6 agents have both `agent.toml` and `system-prompt.md`
|
|
- [ ] All "Must Have" items present and verified
|
|
- [ ] All "Must NOT Have" items absent
|
|
- [ ] `nix flake check` passes on both repos
|
|
- [ ] `nix fmt` produces no changes on both repos
|
|
- [ ] Golden file comparison passes (OpenCode output unchanged)
|
|
- [ ] Claude Code frontmatter valid (name + description present, kebab-case)
|
|
- [ ] Pi output valid (AGENTS.md exists, optional JSON valid)
|
|
- [ ] `lib.mkOpencodeSkills` unchanged and functional
|
|
- [ ] Prompt content byte-identical to originals
|