From 26d004fe467aae8e79076b09a02a0b5346eff4be Mon Sep 17 00:00:00 2001 From: Bryan Ramos Date: Tue, 14 Apr 2026 11:11:23 -0400 Subject: [PATCH] refactor(sources): trim redundant rules, cleanup agent sources, harness-neutral orchestrate - Drop rules/02-responses.md entirely: fully redundant with every harness's built-in system prompt (concise/no-preamble/no-emoji is baked in). - Trim 04-tools.md's Parallelism and Context Management sections; trim 05-verification.md's "run tests" bullet. All covered by harness defaults. - Scope 01-session.md to claude only (memory/ hierarchy is Claude-specific). - Update schemas/team.schema.json const-pin to match the new rules.order. - Strip vestigial Claude-style YAML frontmatter from agents/*.md sources (extract_body was already discarding it; TEAM.yaml is the real source). - Standardize plans/ path: drop \${PLANS_DIR} template var and use literal plans/ everywhere. Claude/codex/opencode now share one plans convention. - Rewrite orchestrate skill team block and permission section to be harness-neutral: drop Claude model parentheticals and permissionMode / disallowedTools terminology. - Rewrite architect agent's "no Bash execution" line generically to avoid naming Claude-specific tool identifiers in prose. Co-Authored-By: Claude Opus 4.6 (1M context) --- TEAM.yaml | 11 -------- agents/architect.md | 21 +++------------ agents/auditor.md | 14 ---------- agents/debugger.md | 13 --------- agents/documenter.md | 15 ----------- agents/grunt.md | 14 ---------- agents/researcher.md | 11 -------- agents/reviewer.md | 13 --------- agents/senior.md | 14 ---------- agents/worker.md | 14 ---------- generate.sh | 53 +++++++++++++------------------------ rules/02-responses.md | 6 ----- rules/04-tools.md | 11 -------- rules/05-verification.md | 1 - schemas/team.schema.json | 12 --------- skills/orchestrate/SKILL.md | 24 ++++++++--------- 16 files changed, 34 insertions(+), 213 deletions(-) delete mode 100644 rules/02-responses.md diff --git a/TEAM.yaml b/TEAM.yaml index 45aba57..5cac499 100644 --- a/TEAM.yaml +++ b/TEAM.yaml @@ -249,7 +249,6 @@ skills: applies_to: - claude - codex - - opencode install_mode: shared qa-checklist: id: qa-checklist @@ -275,7 +274,6 @@ skills: rules: order: - 01-session - - 02-responses - 03-git - 04-tools - 05-verification @@ -286,15 +284,6 @@ rules: source_file: rules/01-session.md applies_to: - claude - - codex - - opencode - 02-responses: - id: 02-responses - source_file: rules/02-responses.md - applies_to: - - claude - - codex - - opencode 03-git: id: 03-git source_file: rules/03-git.md diff --git a/agents/architect.md b/agents/architect.md index c7212e0..d961b61 100644 --- a/agents/architect.md +++ b/agents/architect.md @@ -1,24 +1,11 @@ ---- -name: architect -description: Research-first planning agent. Handles triage, research coordination, architecture design, and wave decomposition. Use before any non-trivial implementation task. Produces the implementation blueprint the entire team follows. -model: opus -effort: max -permissionMode: plan -tools: Read, Glob, Grep, WebFetch, WebSearch, Write -disallowedTools: Edit -maxTurns: 35 -skills: - - conventions - - message-schema ---- You are an architect. You handle the full planning pipeline: triage, architecture design, and wave decomposition. Workers implement exactly what you specify — get it right before anyone writes a line of code. Never implement anything. Never modify source files. Analyze, evaluate, plan. -**Plan persistence:** Always write the approved plan to `${PLANS_DIR}/.md`. Never return the plan inline without writing it first. Check whether a plan file already exists before writing — if it does, continue from it. +**Plan persistence:** Always write the approved plan to `plans/.md`. Never return the plan inline without writing it first. Check whether a plan file already exists before writing — if it does, continue from it. -**Write boundary:** You have write capability only so you can persist plan files. This is not path-enforced by tooling. You must treat writes outside `${PLANS_DIR}/` as forbidden. +**Write boundary:** You have write capability only so you can persist plan files. This is not path-enforced by tooling. You must treat writes outside `plans/` as forbidden. Frontmatter format: ``` @@ -30,7 +17,7 @@ status: active --- ``` -**No Bash execution:** perform repository inspection with Read/Glob/Grep/WebFetch/WebSearch only. +**No shell execution:** perform repository inspection with read-only tools (file reads, code search, ${WEB_SEARCH}) — never run commands. --- @@ -105,7 +92,7 @@ After writing the plan file, return a `plan_result` envelope: --- type: plan_result signal: plan_complete | blocked -plan_file: ${PLANS_DIR}/kebab-case-title.md +plan_file: plans/kebab-case-title.md wave_count: 3 step_count: 7 risk_tags: diff --git a/agents/auditor.md b/agents/auditor.md index 163a987..651123c 100644 --- a/agents/auditor.md +++ b/agents/auditor.md @@ -1,17 +1,3 @@ ---- -name: auditor -description: Use after implementation — audits for security vulnerabilities and validates runtime behavior. Builds, tests, and probes acceptance criteria. Never modifies code. -model: sonnet -background: true -permissionMode: acceptEdits -tools: Read, Glob, Grep, Bash, WebFetch, WebSearch -disallowedTools: Write, Edit -maxTurns: 25 -skills: - - conventions - - message-schema - - qa-checklist ---- You are an auditor. You do two things: security analysis and runtime validation. Never write, edit, or fix code — only identify, validate, and report. diff --git a/agents/debugger.md b/agents/debugger.md index b39a645..db3e360 100644 --- a/agents/debugger.md +++ b/agents/debugger.md @@ -1,16 +1,3 @@ ---- -name: debugger -description: Use immediately when encountering a bug, error, or unexpected behavior. Diagnoses root cause and applies a minimal targeted fix. Does not refactor or improve surrounding code. -model: sonnet -permissionMode: acceptEdits -tools: Read, Write, Edit, Glob, Grep, Bash -maxTurns: 20 -skills: - - conventions - - worker-protocol - - message-schema - - qa-checklist ---- You are a debugger. Your job is to find the root cause of a bug and apply the minimal fix. You do not refactor, improve, or clean up surrounding code — only fix what is broken. diff --git a/agents/documenter.md b/agents/documenter.md index 9855584..8da1650 100644 --- a/agents/documenter.md +++ b/agents/documenter.md @@ -1,18 +1,3 @@ ---- -name: documenter -description: Use when asked to write or update documentation — READMEs, API references, architecture overviews, inline doc comments, or changelogs. Reads code first and updates documentation artifacts only. -model: sonnet -effort: high -memory: project -permissionMode: acceptEdits -tools: Read, Write, Edit, Glob, Grep -maxTurns: 20 -skills: - - conventions - - worker-protocol - - message-schema - - qa-checklist ---- You are a documentation specialist. Your job is to read code and produce accurate, well-structured documentation. You only modify documentation artifacts, and must not change runtime behavior. diff --git a/agents/grunt.md b/agents/grunt.md index 6454d44..db63d95 100644 --- a/agents/grunt.md +++ b/agents/grunt.md @@ -1,17 +1,3 @@ ---- -name: grunt -description: Fast, cheap implementer for trivial and tightly scoped work. Use for one-liners, small renames, simple edits, and low-risk mechanical tasks. Escalate when the work grows beyond that scope. -model: haiku -permissionMode: acceptEdits -isolation: worktree -tools: Read, Write, Edit, Glob, Grep, Bash -maxTurns: 15 -skills: - - conventions - - worker-protocol - - message-schema - - qa-checklist ---- You are a grunt agent. You implement small, explicit tasks quickly and cheaply. diff --git a/agents/researcher.md b/agents/researcher.md index 871dda7..3b12c25 100644 --- a/agents/researcher.md +++ b/agents/researcher.md @@ -1,14 +1,3 @@ ---- -name: researcher -description: Use to answer a specific research question with verified facts. Spawned in parallel — one instance per topic. Stateless. Returns verified facts, source URLs, and gotchas. -model: sonnet -permissionMode: plan -tools: Read, Glob, Grep, WebFetch, WebSearch -disallowedTools: Write, Edit -maxTurns: 10 -skills: - - message-schema ---- You are a researcher. You answer one specific research question with verified facts. You never implement, plan, or make architectural decisions — you find and verify information. diff --git a/agents/reviewer.md b/agents/reviewer.md index 508b83f..3ee054d 100644 --- a/agents/reviewer.md +++ b/agents/reviewer.md @@ -1,16 +1,3 @@ ---- -name: reviewer -description: Use after implementation — reviews code quality and verifies claims against source, docs, and acceptance criteria. Never modifies code. -model: sonnet -permissionMode: plan -tools: Read, Glob, Grep, WebFetch, WebSearch -disallowedTools: Write, Edit -maxTurns: 20 -skills: - - conventions - - message-schema - - qa-checklist ---- You are a reviewer. You do two things in one pass: quality review and claim verification. Never write, edit, or fix code — only flag and explain. diff --git a/agents/senior.md b/agents/senior.md index 9a4acef..644c817 100644 --- a/agents/senior.md +++ b/agents/senior.md @@ -1,17 +1,3 @@ ---- -name: senior -description: Strong implementer for ambiguous, architectural, or high-risk work. Use when the task spans multiple files, requires careful judgment, or has already failed in a cheaper worker. Default escalation path for hard implementation work. -model: opus -permissionMode: acceptEdits -isolation: worktree -tools: Read, Write, Edit, Glob, Grep, Bash -maxTurns: 35 -skills: - - conventions - - worker-protocol - - message-schema - - qa-checklist ---- You are a senior agent. You implement difficult or ambiguous tasks with strong technical judgment. diff --git a/agents/worker.md b/agents/worker.md index 5318d84..bc5a93c 100644 --- a/agents/worker.md +++ b/agents/worker.md @@ -1,17 +1,3 @@ ---- -name: worker -description: Balanced implementer for standard development work. Use when the task is well-defined but not trivial. Escalate upward for architectural ambiguity and downward for tiny mechanical changes. -model: sonnet -permissionMode: acceptEdits -isolation: worktree -tools: Read, Write, Edit, Glob, Grep, Bash -maxTurns: 25 -skills: - - conventions - - worker-protocol - - message-schema - - qa-checklist ---- You are a worker agent. You implement standard development tasks. Your orchestrator may resume you to iterate on feedback or continue related work. diff --git a/generate.sh b/generate.sh index c25fd97..00193b1 100755 --- a/generate.sh +++ b/generate.sh @@ -263,7 +263,7 @@ map_portable_tool_to_claude() { # map_model_to_opencode — all models map to the single local model # --------------------------------------------------------------------------- map_model_to_opencode() { - echo "llama.cpp/qwen3-coder:a3b" + echo "llama-stack/llamacpp/Qwen3-Coder-30B-A3B-Instruct-Q8_0" } # --------------------------------------------------------------------------- @@ -284,11 +284,7 @@ map_effort_to_temperature() { # map_permission_mode_to_opencode_mode — maps permission mode to agent mode # --------------------------------------------------------------------------- map_permission_mode_to_opencode_mode() { - local permission_mode="$1" - case "$permission_mode" in - plan) echo "subagent" ;; - *) echo "primary" ;; - esac + echo "subagent" } # --------------------------------------------------------------------------- @@ -302,43 +298,30 @@ generate_opencode_permission_block() { local disallowed_tools="$2" local permission_mode="$3" + # Helper: is CLAUDE tool $1 present in $tools and not in $disallowed_tools? + tool_allowed() { + local t="$1" + echo "$tools" | grep -qE "\b${t}\b" || return 1 + echo "$disallowed_tools" | grep -qE "\b${t}\b" && return 1 + return 0 + } + + local write_perm="deny" local edit_perm="deny" local bash_perm="deny" local webfetch_perm="deny" - if [ "$permission_mode" = "plan" ]; then - # Plan-mode agents: read-only, no edits, no bash - edit_perm="deny" - bash_perm="deny" - # Researchers/reviewers still need web access - if echo "$tools" | grep -qE '\bWebFetch\b|\bWebSearch\b'; then - webfetch_perm="allow" - fi - else - # Check edit permission - if echo "$tools" | grep -qE '\bWrite\b|\bEdit\b'; then - edit_perm="allow" - fi - if echo "$disallowed_tools" | grep -qE '\bWrite\b|\bEdit\b'; then - edit_perm="deny" - fi + tool_allowed "Write" && write_perm="allow" + tool_allowed "Edit" && edit_perm="allow" + tool_allowed "Bash" && bash_perm="ask" - # Check bash permission - if echo "$tools" | grep -q '\bBash\b'; then - bash_perm="ask" - fi - if echo "$disallowed_tools" | grep -q '\bBash\b'; then - bash_perm="deny" - fi - - # Check web permission - if echo "$tools" | grep -qE '\bWebFetch\b|\bWebSearch\b'; then - webfetch_perm="allow" - fi + if tool_allowed "WebFetch" || tool_allowed "WebSearch"; then + webfetch_perm="allow" fi echo "permission:" echo " edit: ${edit_perm}" + echo " write: ${write_perm}" if [ "$bash_perm" = "ask" ]; then echo " bash:" @@ -346,7 +329,7 @@ generate_opencode_permission_block() { echo " \"git status\": allow" echo " \"git diff *\": allow" echo " \"git log *\": allow" - elif [ "$bash_perm" = "deny" ]; then + else echo " bash:" echo " \"*\": deny" fi diff --git a/rules/02-responses.md b/rules/02-responses.md deleted file mode 100644 index 2dbbdf1..0000000 --- a/rules/02-responses.md +++ /dev/null @@ -1,6 +0,0 @@ -# Responses & Explanations - -- Be concise — lead with the action or answer, not the preamble -- Include just enough reasoning to explain *why* a decision was made, not a full walkthrough -- Skip trailing summaries ("Here's what I did...") — the diff speaks for itself -- No emojis unless explicitly asked diff --git a/rules/04-tools.md b/rules/04-tools.md index 53be043..66a6cbf 100644 --- a/rules/04-tools.md +++ b/rules/04-tools.md @@ -20,14 +20,3 @@ - Commonly run development workflows MUST be wired into `just` recipes as the user-facing entrypoints - Temporary artifacts created during work MUST be cleaned up before completion unless the user explicitly asked to keep them -# Parallelism - -- Always parallelize independent work — tool calls, file reads, searches -- When a task has components that don't depend on each other, run them concurrently by default -- Sequential execution is allowed only when required by dependencies or operational constraints (tool/runtime limits, contention, staged validation) - -# Context Management - -- Use subagents for exploratory reads and investigations to keep the main context clean -- Use scoped file reads (offset/limit) over reading entire large files -- When a task is complete or the topic shifts significantly, suggest clearing context or starting a new session diff --git a/rules/05-verification.md b/rules/05-verification.md index 4965eeb..c0f91df 100644 --- a/rules/05-verification.md +++ b/rules/05-verification.md @@ -1,6 +1,5 @@ # Verification -- After making changes, run relevant tests or build commands to verify correctness before reporting success - If no tests exist for the changed code, say so rather than silently assuming it works - Run single targeted tests by default; run the full suite when requested or when targeted coverage is insufficient diff --git a/schemas/team.schema.json b/schemas/team.schema.json index 0d9668c..0fbd268 100644 --- a/schemas/team.schema.json +++ b/schemas/team.schema.json @@ -470,7 +470,6 @@ "uniqueItems": true, "const": [ "01-session", - "02-responses", "03-git", "04-tools", "05-verification", @@ -482,7 +481,6 @@ "additionalProperties": false, "required": [ "01-session", - "02-responses", "03-git", "04-tools", "05-verification", @@ -499,16 +497,6 @@ } ] }, - "02-responses": { - "allOf": [ - { "$ref": "#/$defs/rule_item" }, - { - "properties": { - "id": { "const": "02-responses" } - } - } - ] - }, "03-git": { "allOf": [ { "$ref": "#/$defs/rule_item" }, diff --git a/skills/orchestrate/SKILL.md b/skills/orchestrate/SKILL.md index c743034..0cb13d8 100644 --- a/skills/orchestrate/SKILL.md +++ b/skills/orchestrate/SKILL.md @@ -10,17 +10,19 @@ You are now acting as orchestrator. Decompose, delegate, validate, deliver. Neve ``` You (orchestrator) - ├── grunt (haiku) — trivial, cheap implementer - ├── worker (sonnet) — standard implementer - ├── senior (opus) — ambiguous, architectural, or high-risk implementer - ├── debugger (sonnet) — bug diagnosis and minimal fixes - ├── documenter (sonnet) — documentation only, never touches source - ├── researcher (sonnet) — one per topic, parallel fact-finding - ├── architect (opus, effort: max) — triage, research coordination, architecture, wave decomposition - ├── reviewer (sonnet) — code quality + AC verification + claim checking - └── auditor (sonnet, background) — security analysis + runtime validation + ├── grunt — trivial, cheap implementer + ├── worker — standard implementer + ├── senior — ambiguous, architectural, or high-risk implementer + ├── debugger — bug diagnosis and minimal fixes + ├── documenter — documentation only, never touches source + ├── researcher — one per topic, parallel fact-finding + ├── architect — triage, research coordination, architecture, wave decomposition + ├── reviewer — code quality + AC verification + claim checking + └── auditor — security analysis + runtime validation ``` +Models and effort levels are pinned per-agent in each harness's config. Pick agents by role; the harness handles model selection. + --- ## Task tiers @@ -201,9 +203,7 @@ When multiple risk tags are present, take the union. Spawn all required reviewer ### Permission model -Agent `permissionMode` in frontmatter is overridden when the parent (you, the orchestrator) runs in `acceptEdits` or `bypassPermissions` mode — the child inherits the parent's mode. This means `permissionMode: plan` on read-only agents like architect, researcher, and reviewer is **not enforced at runtime**. - -The actual write protection for read-only agents comes from `disallowedTools: Write, Edit` — this is enforced regardless of permission mode. Do not rely on `permissionMode` as a safety boundary; rely on tool restrictions. +Each agent declares its allowed tools in its frontmatter — read-only agents (architect, researcher, reviewer, auditor) cannot write, edit, or run shell commands because those tools are denied at the agent level, not gated by a runtime mode. Trust the per-agent tool restrictions as the real safety boundary. If a read-only agent needs to escalate to a write, route the work through an implementer instead of loosening permissions. ### Parallelism mandate