special-agents 0.8.10 → 0.8.11

package/README.md

@@ -1,6 +1,6 @@
 # special-agents
 
-29 composable best-practice rule packs, 6 skills, and 4 agent roles for Claude Code and Codex.
+Composable best-practice rule packs, skills, and agent roles for Claude Code and Codex.
 
 The content layer of [Rafi](https://github.com/ttante/rafi). Ships both the authoring source (`content/`) and prebuilt composition logic so it can be used as a library, consumed by `rafi compile`, or extended directly.
 
@@ -13,14 +13,17 @@ npm install special-agents
 ## Usage
 
 ```ts
-import { getAgent, getSkill, emitCompiledBundles } from "special-agents";
+import { getAgent, loadSkill, emitCompiledBundles } from "special-agents";
 
 // Get a composed role bundle (system prompt + skills list)
 const { system, skills } = getAgent("builder");
 // system → assembled prompt with all applicable rule packs rendered
-// skills → ["tdd", "improve-codebase-architecture"]
+// skills → ["handoff", "tdd", "improve-codebase-architecture"]
 
-// Write compiled role bundles + AGENTS.md + CLAUDE.md to a target repo
+// Read a standalone implementation workflow
+const implementor = loadSkill("implementor");
+
+// Write compiled role bundles to a target repo
 emitCompiledBundles("./my-repo", {
   defaults: {
     stack: { frontend: "React", backend: "Node.js", database: "PostgreSQL", cloud: "AWS", packageManager: "pnpm" },
@@ -29,6 +32,24 @@ emitCompiledBundles("./my-repo", {
 });
 ```
 
+## Implementor skill
+
+[`implementor`](content/skills/implementor/SKILL.md) carries a scoped feature, bug fix, or plan through implementation, verification, a durable checkpoint, review, and corrections. It supports compact-then-audit workflows, prefers an independent final review when available and permitted, and labels the fallback as self-review. Its [review checklist](content/skills/implementor/references/review.md) checks requirements separately from code quality and asks for evidence behind findings.
+
+New Rafi projects include it in their default skill configuration. For an existing project with an explicit `skills` map, merge this entry under `skills` in `rafi-config.yaml`, then run `rafi compile .` using a CLI build containing this skill:
+
+```yaml
+skills:
+  implementor:
+    artifact_source: rafi
+    claude: ./.claude/skills/implementor/SKILL.md
+    codex: ./.agents/skills/implementor/SKILL.md
+```
+
+Compilation copies the skill and its review reference into the selected runtimes' skill directories. In an agent session, request it by name, for example: "Use the implementor skill to implement the plan in docs/plan.md, then audit and fix the result."
+
+The skill provides workflow instructions; actual compaction and independent review depend on the host's capabilities and permissions. When used within Rafi's Builder/QA loop, it respects the assigned step and host-owned review and handoff protocols.
+
 ## Roles
 
 | Role | Description |

package/content/skills/implementor/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: implementor
+description: Implement a scoped feature, bug fix, or existing plan through incremental changes, verification, a durable checkpoint, and an evidence-based review/fix loop. Use for implement-then-audit workflows, including resuming after compaction. Not for planning-only requests or standalone reviews of unrelated work.
+---
+
+# Implementor
+
+Carry the requested change through implementation, verification, review, and correction. Preserve enough factual state to resume after compaction without repeating completed work or mistaking assumptions for evidence.
+
+Default flow: **establish criteria → implement and verify → checkpoint → review → fix and reverify → report**. Scale the process to the change: a small edit needs a short check, not a new planning exercise. Continue authorized work without asking for approval between phases.
+
+## Establish the task and baseline
+
+- Read the original request, any supplied plan, relevant repository instructions, and the code and callers affected by the change. Reuse the existing plan; create only the missing detail needed to act.
+- Identify observable acceptance criteria, scope exclusions, and relevant verification commands. Separate requirements from implementation suggestions. Resolve routine choices using repository conventions; clarify only uncertainties that materially change behavior, scope, or authorization, while continuing independent work.
+- Record the starting revision and working-tree state before editing. Distinguish pre-existing staged, unstaged, and untracked work from this task's changes. When changes overlap, preserve a baseline diff or equivalent record so later review can identify your contribution. In a repository without Git, track the initial state of affected files instead.
+- Use existing verification results or run a relevant baseline check when it helps distinguish an existing failure from a regression. Avoid rerunning unrelated suites solely to establish a baseline.
+
+## Implement in verifiable steps
+
+- Work in small behavior-focused steps that keep the change reviewable. For application behavior and bug fixes, prefer a test or reproduction that fails for the expected reason before the fix and passes afterward. Follow the project's testing conventions; test observable behavior rather than mirroring implementation details. If test-first work is impractical, use the best available check and record its limits.
+- Run targeted checks as each meaningful step lands. Use the repository's required quality checks before declaring completion. Inspect exit status and results; a passing lint run is not evidence that the build or behavior works.
+- When a check fails unexpectedly, reproduce it, trace the cause, and test a specific hypothesis before adding more changes. Do not weaken assertions, suppress errors, or revise acceptance criteria merely to obtain a pass.
+- Keep refactoring proportional to the task. Update affected contracts, documentation, configuration, and operational instructions when the behavior requires it.
+- Verification applies to the state that was checked. After a relevant edit, rerun affected checks; do not rerun unchanged checks merely to produce a newer timestamp.
+
+## Checkpoint and compaction
+
+Maintain a factual checkpoint for work spanning multiple steps or sessions, and always before a deliberate compaction or transfer. Update the task's existing work log if suitable; otherwise use a task-specific file such as `.implementor/<task-id>/checkpoint.md`. Choose a unique task ID, preserve other tasks' notes, and report the checkpoint path so a successor can find it. Tiny changes that stay in one context do not require a separate file.
+
+Keep the checkpoint concise and cumulative. Preserve unresolved decisions and failed approaches that affect the next action; reference large artifacts instead of copying transcripts or logs. Record:
+
+```text
+Task: original request or stable source, acceptance criteria, scope exclusions
+Phase: implementing | ready for review | fixing findings | complete | blocked
+Baseline: starting revision, pre-existing changes, baseline-record location
+Changes: completed steps, touched/new files, task commits if any
+Verification: commands, outcomes, checked revision/state, unrun checks and reasons
+Decisions: relevant constraints, assumptions, deviations and their reasons
+Review: independent or self-review, reviewed state, findings and dispositions
+Remaining: unfinished criteria, unresolved findings, known failures
+Next action: exact next step and files to read
+```
+
+Honor a requested compact-before-audit boundary after implementation and initial verification. Use an actual runtime compaction facility when available; writing a summary does not compact a session. If the user requires compaction before review and only the user can trigger it, save the checkpoint and report the required runtime action and how to resume at review. Otherwise, unavailable compaction should not prevent review. Never claim a context reset that did not occur.
+
+On resumption, read the checkpoint and original requirements, then inspect current files, diffs, and relevant history. Reconcile changes made since the checkpoint; do not replay completed steps or rely on remembered file contents. Treat recorded test results as historical evidence for the recorded state.
+
+## Audit the result
+
+Read [references/review.md](references/review.md) at the review phase. Review the whole task change, including committed, staged, unstaged, and new files attributable to the task, and inspect surrounding code where needed. A last-commit diff alone may omit most of the implementation.
+
+Prefer one independent final reviewer in a fresh context when delegation is available and permitted. Give it the original requirements, relevant repository constraints, exact change scope/baseline, and the review checklist. Have it inspect the code and form an assessment before reading the implementor's conclusions. Avoid passing the implementation conversation or a persuasive completion narrative. The reviewer should report findings without editing files; the implementor owns corrections.
+
+If a host already schedules QA, use that review boundary and its required output protocol instead of launching a duplicate reviewer. In Rafi, stay within the assigned ticket/step and let the host own QA, session transfers, and task-state transitions. An ordinary checkpoint does not replace Rafi's structured `handoff` protocol.
+
+If independent review is unavailable or disallowed, perform the same checklist yourself and label it **self-review**. Compaction alone does not make a review independent. Use additional reviews during implementation only when the size or risk justifies them, or the user requests them.
+
+## Resolve findings and finish
+
+- Check each finding against the requirements and actual code. Reproduce the failure or establish a concrete failing path before fixing it. Record each as fixed, rejected with evidence, or unresolved with its impact; distinguish optional improvements from completion blockers.
+- Fix supported, in-scope defects, adding a regression check when it meaningfully protects the behavior. Rerun affected checks and review the correction and nearby interactions. Reopen broader review only when the correction changes the design or exposes a wider concern.
+- If two successive correction cycles revisit the same issue without new evidence, stop guessing: investigate the root cause or missing requirement. If progress requires an external decision or unavailable resource, report the specific blocker and continue independent work. Never silently waive a requirement to end the loop.
+- Finish when the acceptance criteria are supported by evidence, required checks have passed, and confirmed in-scope defects are resolved. Otherwise report the work as incomplete or verification-limited, with the exact gap. Defer a known defect only when the user's scope or decision permits it, and disclose the deferral.
+
+The final report should state the resulting behavior, checks run and their outcomes, review mode and resolved findings, and any remaining gaps. Include the checkpoint path when one exists. Do not equate unrun checks with passes or a review with a guarantee of correctness. Committing, publishing, deployment, and unrelated cleanup follow the user's requested scope; they are not automatic completion steps.

package/content/skills/implementor/references/review.md

@@ -0,0 +1,44 @@
+# Implementation review
+
+Use this checklist after implementation, or when resuming at the audit phase. Review evidence before accepting the implementor's assessment. Report supported defects and requirements gaps; do not invent findings to fill a quota.
+
+## Establish review scope
+
+Read the original request or spec, acceptance criteria, relevant repository instructions, and the task's baseline/change scope. Include all task changes, including new files and changes spread over multiple commits. Inspect callers and unchanged surrounding code when needed to understand behavior. Do not attribute pre-existing work to the implementor; if overlapping changes make attribution uncertain, say so and assess their interaction explicitly.
+
+If supplied material is insufficient, inspect the repository for the missing evidence. Mark remaining limits on coverage. Keep review read-only with respect to source files; use permitted checks in an isolated or otherwise appropriate environment when they have side effects.
+
+## Pass 1: Requirements and scope
+
+- Map each acceptance criterion to the code path that implements it and the evidence that exercises it. Passing tests alone do not establish that all requirements were implemented.
+- Look for omitted behavior, partial implementations, changed contracts, and defaults that conflict with the request. Follow important paths from the real entry point; a correct helper that is never called does not satisfy the task.
+- Identify unsupported assumptions and unrequested behavior changes. Distinguish mandatory requirements from optional suggestions or preferences.
+- Check associated configuration, documentation, migrations, and operational steps only where the change requires them.
+
+## Pass 2: Correctness and test quality
+
+Apply the relevant checks, rather than every category on every task:
+
+- **Behavior and integration:** trace representative inputs through callers, boundary conversions, persistence, and outputs. Check compatibility with existing interfaces and consumers.
+- **Failure and lifecycle behavior:** inspect error handling, partial failures, cancellation, cleanup, retries, duplicate execution, and concurrency where applicable. Look for swallowed errors and success reported before work is durable.
+- **Trust boundaries:** check authorization, validation, secrets handling, and unsafe interpretation of data where the change touches them.
+- **User-visible behavior:** check the actual CLI/API/UI entry point. For UI changes, inspect the rendered result and important interactions when possible, including relevant accessibility behavior.
+- **Tests:** determine whether they would detect an incorrect implementation. Watch for tautological assertions, mocks that bypass the changed behavior, missing failure cases, skipped tests, and expectations changed to match a bug. Prefer behavior checks over internal structure assertions.
+- **Maintainability:** flag complexity or duplication when it creates a concrete correctness or maintenance problem. Keep stylistic preferences and speculative abstractions separate from defects.
+
+Inspect verification evidence after forming your initial assessment. Check which code state it covers and whether the commands exercise the claims being made. Run a targeted reproduction when needed and permitted; do not claim commands you did not run or treat a partial check as proof of the whole system.
+
+## Finding format
+
+For each actionable finding, provide:
+
+- **Severity and location:** blocking, important, or minor; relevant file and line or symbol.
+- **Trigger and impact:** a concrete input, state, or execution sequence and the resulting incorrect behavior.
+- **Evidence:** a reproduction, test result, or traceable code path, and the requirement or contract it violates.
+- **Correction direction:** the smallest reasonable fix, without prescribing an unrelated redesign.
+
+Define blocking as preventing an acceptance criterion or safe operation; important as a material bug in scope; minor as a supported lower-impact defect. Keep optional improvements separate. Express uncertain issues as hypotheses needing verification, not established bugs. A valid review may find no actionable issues; state coverage and limitations instead of certifying the code as bug-free.
+
+## Re-review after corrections
+
+Confirm that each accepted finding is fixed and that the correction preserves nearby behavior. Recheck affected acceptance criteria and tests. Carry unresolved findings forward explicitly. Broaden the review only if the correction expands scope or changes assumptions that earlier conclusions depended on.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "special-agents",
-  "version": "0.8.10",
+  "version": "0.8.11",
   "description": "Rafi library: composable best-practice rules, skills, and agents for Claude Code and Codex.",
   "license": "Apache-2.0",
   "type": "module",
@@ -36,7 +36,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "rafi-spec": "0.8.11",
+    "rafi-spec": "0.8.12",
     "ajv": "^8.20.0",
     "yaml": "^2.5.1"
   },