Compare commits

...

2 Commits

Author SHA1 Message Date
Affaan Mustafa
32e9c293f0 chore: replace external repo links with @username attribution 2026-03-03 12:32:35 -08:00
Affaan Mustafa
cd129edef0 feat(skills): add autonomous-loops and plankton-code-quality skills
- autonomous-loops: 6 loop patterns from simple claude -p pipelines to
  RFC-driven DAG orchestration (Ralphinho, infinite-agentic-loop,
  continuous-claude, de-sloppify pattern)
- plankton-code-quality: write-time enforcement integration guide
- README: updated directory listing and Plankton description

Sources: enitrat/ralphinho, disler/infinite-agentic-loop,
AnandChowdhary/continuous-claude, alexfazio/plankton
2026-03-03 12:16:57 -08:00
24 changed files with 837 additions and 27 deletions

View File

@@ -283,6 +283,8 @@ everything-claude-code/
| |-- liquid-glass-design/ # iOS 26 Liquid Glass design system (NEW)
| |-- foundation-models-on-device/ # Apple on-device LLM with FoundationModels (NEW)
| |-- swift-concurrency-6-2/ # Swift 6.2 Approachable Concurrency (NEW)
| |-- autonomous-loops/ # Autonomous loop patterns: sequential pipelines, PR loops, DAG orchestration (NEW)
| |-- plankton-code-quality/ # Write-time code quality enforcement with Plankton hooks (NEW)
|
|-- commands/ # Slash commands for quick execution
| |-- tdd.md # /tdd - Test-driven development
@@ -442,9 +444,9 @@ Use `/security-scan` in Claude Code to run it, or add to CI with the [GitHub Act
[GitHub](https://github.com/affaan-m/agentshield) | [npm](https://www.npmjs.com/package/ecc-agentshield)
### 🔬 Plankton — Code Quality Integration
### 🔬 Plankton — Write-Time Code Quality Enforcement
[Plankton](https://github.com/alexfazio/plankton) is a recommended companion for code quality enforcement. It provides automated code review, linting orchestration, and quality gates that pair well with the ECC skill and hook system. Use it alongside AgentShield for security + quality coverage.
Plankton (credit: @alxfazio) is a recommended companion for write-time code quality enforcement. It runs formatters and 20+ linters on every file edit via PostToolUse hooks, then spawns Claude subprocesses (routed to Haiku/Sonnet/Opus by violation complexity) to fix issues the main agent missed. Three-phase architecture: auto-format silently (40-50% of issues), collect remaining violations as structured JSON, delegate fixes to a subprocess. Includes config protection hooks that prevent agents from modifying linter configs to pass instead of fixing code. Supports Python, TypeScript, Shell, YAML, JSON, TOML, Markdown, and Dockerfile. Use alongside AgentShield for security + quality coverage. See `skills/plankton-code-quality/` for full integration guide.
### 🧠 Continuous Learning v2
@@ -905,7 +907,7 @@ Skills at `.agents/skills/` are auto-loaded by Codex:
### Key Limitation
Codex CLI does **not yet support hooks** ([GitHub Issue #2109](https://github.com/openai/codex/issues/2109), 430+ upvotes). Security enforcement is instruction-based via `persistent_instructions` in config.toml and the sandbox permission system.
Codex CLI does **not yet support hooks** (OpenAI Codex Issue #2109, 430+ upvotes). Security enforcement is instruction-based via `persistent_instructions` in config.toml and the sandbox permission system.
---

View File

@@ -146,6 +146,6 @@ claude /schedule-reply "Reply to Sarah about the board meeting"
## Prerequisites
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
- Gmail CLI (e.g., [gog](https://github.com/pterm/gog))
- Gmail CLI (e.g., gog by @pterm)
- Node.js 18+ (for calendar-suggest.js)
- Optional: Slack MCP server, Matrix bridge (LINE), Chrome + Playwright (Messenger)

View File

@@ -7,7 +7,7 @@ model: sonnet
# Database Reviewer
You are an expert PostgreSQL database specialist focused on query optimization, schema design, security, and performance. Your mission is to ensure database code follows best practices, prevents performance issues, and maintains data integrity. Incorporates patterns from [Supabase's postgres-best-practices](https://github.com/supabase/agent-skills).
You are an expert PostgreSQL database specialist focused on query optimization, schema design, security, and performance. Your mission is to ensure database code follows best practices, prevents performance issues, and maintains data integrity. Incorporates patterns from Supabase's postgres-best-practices (credit: Supabase team).
## Core Responsibilities
@@ -88,4 +88,4 @@ For detailed index patterns, schema design examples, connection management, conc
**Remember**: Database issues are often the root cause of application performance problems. Optimize queries and schema design early. Use EXPLAIN ANALYZE to verify assumptions. Always index foreign keys and RLS policy columns.
*Patterns adapted from [Supabase Agent Skills](https://github.com/supabase/agent-skills) under MIT license.*
*Patterns adapted from Supabase Agent Skills (credit: Supabase team) under MIT license.*

View File

@@ -7,7 +7,7 @@ model: opus
# データベースレビューアー
あなたはクエリ最適化、スキーマ設計、セキュリティ、パフォーマンスに焦点を当てたエキスパートPostgreSQLデータベーススペシャリストです。あなたのミッションは、データベースコードがベストプラクティスに従い、パフォーマンス問題を防ぎ、データ整合性を維持することを確実にすることです。このエージェントは[SupabaseのPostgreSQLベストプラクティス](https://github.com/supabase/agent-skills)からのパターンを組み込んでいます。
あなたはクエリ最適化、スキーマ設計、セキュリティ、パフォーマンスに焦点を当てたエキスパートPostgreSQLデータベーススペシャリストです。あなたのミッションは、データベースコードがベストプラクティスに従い、パフォーマンス問題を防ぎ、データ整合性を維持することを確実にすることです。このエージェントは[SupabaseのPostgreSQLベストプラクティス](Supabase Agent Skills (credit: Supabase team))からのパターンを組み込んでいます。
## 主な責務
@@ -651,4 +651,4 @@ ORDER BY rank DESC;
**覚えておくこと**: データベースの問題は、アプリケーションパフォーマンス問題の根本原因であることが多いです。クエリとスキーマ設計を早期に最適化してください。仮定を検証するためにEXPLAIN ANALYZEを使用してください。常に外部キーとRLSポリシー列にインデックスを作成してください。
*パターンはMITライセンスの下で[Supabase Agent Skills](https://github.com/supabase/agent-skills)から適応されています。*
*パターンはMITライセンスの下で[Supabase Agent Skills](Supabase Agent Skills (credit: Supabase team))から適応されています。*

View File

@@ -15,7 +15,8 @@
claude plugin marketplace add https://github.com/anthropics/claude-plugins-official
# コミュニティマーケットプレイスを追加
claude plugin marketplace add https://github.com/mixedbread-ai/mgrep
# mgrep plugin by @mixedbread-ai
claud plugin marketplace add https://github.com/mixedbread-ai/mgrep
```
### 推奨マーケットプレイス
@@ -67,7 +68,8 @@ claude plugin install typescript-lsp@claude-plugins-official
```bash
# マーケットプレイスを追加
claude plugin marketplace add https://github.com/anthropics/claude-plugins-official
claude plugin marketplace add https://github.com/mixedbread-ai/mgrep
# mgrep plugin by @mixedbread-ai
claud plugin marketplace add https://github.com/mixedbread-ai/mgrep
# /pluginsを開き、必要なものをインストール
```

View File

@@ -160,7 +160,7 @@ include(FetchContent)
set(GTEST_VERSION v1.17.0) # プロジェクトポリシーに合わせて調整します。
FetchContent_Declare(
googletest
URL https://github.com/google/googletest/archive/refs/tags/${GTEST_VERSION}.zip
URL Google Test framework (official repository) https://github.com/google/googletest/archive/refs/tags/${GTEST_VERSION}.zip
)
FetchContent_MakeAvailable(googletest)

View File

@@ -143,4 +143,4 @@ SELECT pg_reload_conf();
---
*[Supabase Agent Skills](https://github.com/supabase/agent-skills)MITライセンスに基づく*
*[Supabase Agent Skills](Supabase Agent Skills (credit: Supabase team))MITライセンスに基づく*

View File

@@ -150,6 +150,6 @@ claude /schedule-reply "Reply to Sarah about the board meeting"
## 先决条件
* [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
* Gmail CLI (例如 [gog](https://github.com/pterm/gog))
* Gmail CLI (例如 [gog](https://gog by @pterm))
* Node.js 18+ (用于 calendar-suggest.js)
* 可选Slack MCP 服务器、Matrix 桥接 (LINE)、Chrome + Playwright (Messenger)

View File

@@ -7,7 +7,7 @@ model: sonnet
# 数据库审查员
您是一位专注于查询优化、模式设计、安全性和性能的 PostgreSQL 数据库专家。您的任务是确保数据库代码遵循最佳实践、防止性能问题并保持数据完整性。融合了 [Supabase 的 postgres-best-practices](https://github.com/supabase/agent-skills) 中的模式。
您是一位专注于查询优化、模式设计、安全性和性能的 PostgreSQL 数据库专家。您的任务是确保数据库代码遵循最佳实践、防止性能问题并保持数据完整性。融合了 [Supabase 的 postgres-best-practices](Supabase Agent Skills (credit: Supabase team)) 中的模式。
## 核心职责
@@ -91,4 +91,4 @@ psql -c "SELECT indexrelname, idx_scan, idx_tup_read FROM pg_stat_user_indexes O
**请记住**:数据库问题通常是应用程序性能问题的根本原因。尽早优化查询和模式设计。使用 EXPLAIN ANALYZE 来验证假设。始终对外键和 RLS 策略列建立索引。
*模式改编自 [Supabase Agent Skills](https://github.com/supabase/agent-skills),遵循 MIT 许可证。*
*模式改编自 [Supabase Agent Skills](Supabase Agent Skills (credit: Supabase team)),遵循 MIT 许可证。*

View File

@@ -9,7 +9,7 @@ version: 2.0.0
一个高级学习系统,通过原子化的“本能”——带有置信度评分的小型习得行为——将你的 Claude Code 会话转化为可重用的知识。
部分灵感来源于 [humanplane](https://github.com/humanplane) 的 Homunculus 项目。
部分灵感来源于 humanplane (credit: @humanplane) 的 Homunculus 项目。
## 何时激活

View File

@@ -161,7 +161,7 @@ include(FetchContent)
set(GTEST_VERSION v1.17.0) # Adjust to project policy.
FetchContent_Declare(
googletest
URL https://github.com/google/googletest/archive/refs/tags/${GTEST_VERSION}.zip
URL Google Test framework (official repository) https://github.com/google/googletest/archive/refs/tags/${GTEST_VERSION}.zip
)
FetchContent_MakeAvailable(googletest)

View File

@@ -151,4 +151,4 @@ SELECT pg_reload_conf();
***
*基于 [Supabase Agent Skills](https://github.com/supabase/agent-skills) (MIT License)*
*基于 [Supabase Agent Skills](Supabase Agent Skills (credit: Supabase team)) (MIT License)*

View File

@@ -137,7 +137,7 @@ alias claude-research='claude --system-prompt "$(cat ~/.claude/contexts/research
用 mgrep 替换 grep——与传统 grep 或 ripgrep 相比,平均减少约 50% 的令牌:
![mgrep Benchmark](../../assets/images/longform/06-mgrep-benchmark.png)
*在我们的 50 项任务基准测试中mgrep + Claude Code 使用的 token 数量比基于 grep 的工作流少约 2 倍,且判断质量相似或更好。来源:https://github.com/mixedbread-ai/mgrep*
*在我们的 50 项任务基准测试中mgrep + Claude Code 使用的 token 数量比基于 grep 的工作流少约 2 倍,且判断质量相似或更好。来源:mgrep by @mixedbread-ai*
**模块化代码库的好处:**

View File

@@ -162,6 +162,7 @@ MCP 将 Claude 直接连接到外部服务。它不是 API 的替代品——而
```bash
# Add a marketplace
# mgrep plugin by @mixedbread-ai
claude plugin marketplace add https://github.com/mixedbread-ai/mgrep
# Open Claude, run /plugins, find new marketplace, install from there

View File

@@ -7,7 +7,7 @@ model: opus
# 資料庫審查員
您是一位專注於查詢優化、結構描述設計、安全性和效能的 PostgreSQL 資料庫專家。您的任務是確保資料庫程式碼遵循最佳實務、預防效能問題並維護資料完整性。此 Agent 整合了來自 [Supabase 的 postgres-best-practices](https://github.com/supabase/agent-skills) 的模式。
您是一位專注於查詢優化、結構描述設計、安全性和效能的 PostgreSQL 資料庫專家。您的任務是確保資料庫程式碼遵循最佳實務、預防效能問題並維護資料完整性。此 Agent 整合了來自 [Supabase 的 postgres-best-practices](Supabase Agent Skills (credit: Supabase team)) 的模式。
## 核心職責
@@ -375,4 +375,4 @@ RETURNING *;
**記住**:資料庫問題通常是應用程式效能問題的根本原因。儘早優化查詢和結構描述設計。使用 EXPLAIN ANALYZE 驗證假設。總是為外鍵和 RLS 政策欄位建立索引。
*模式改編自 [Supabase Agent Skills](https://github.com/supabase/agent-skills)MIT 授權。*
*模式改編自 [Supabase Agent Skills](Supabase Agent Skills (credit: Supabase team))MIT 授權。*

View File

@@ -143,4 +143,4 @@ SELECT pg_reload_conf();
---
*基於 [Supabase Agent Skills](https://github.com/supabase/agent-skills)MIT 授權)*
*基於 [Supabase Agent Skills](Supabase Agent Skills (credit: Supabase team))MIT 授權)*

View File

@@ -14,7 +14,7 @@ Marketplaces are repositories of installable plugins.
# Add official Anthropic marketplace
claude plugin marketplace add https://github.com/anthropics/claude-plugins-official
# Add community marketplaces
# Add community marketplaces (mgrep by @mixedbread-ai)
claude plugin marketplace add https://github.com/mixedbread-ai/mgrep
```
@@ -24,7 +24,7 @@ claude plugin marketplace add https://github.com/mixedbread-ai/mgrep
|-------------|--------|
| claude-plugins-official | `anthropics/claude-plugins-official` |
| claude-code-plugins | `anthropics/claude-code` |
| Mixedbread-Grep | `mixedbread-ai/mgrep` |
| Mixedbread-Grep (@mixedbread-ai) | `mixedbread-ai/mgrep` |
---

View File

@@ -0,0 +1,607 @@
---
name: autonomous-loops
description: "Patterns and architectures for autonomous Claude Code loops — from simple sequential pipelines to RFC-driven multi-agent DAG systems."
origin: ECC
---
# Autonomous Loops Skill
Patterns, architectures, and reference implementations for running Claude Code autonomously in loops. Covers everything from simple `claude -p` pipelines to full RFC-driven multi-agent DAG orchestration.
## When to Use
- Setting up autonomous development workflows that run without human intervention
- Choosing the right loop architecture for your problem (simple vs complex)
- Building CI/CD-style continuous development pipelines
- Running parallel agents with merge coordination
- Implementing context persistence across loop iterations
- Adding quality gates and cleanup passes to autonomous workflows
## Loop Pattern Spectrum
From simplest to most sophisticated:
| Pattern | Complexity | Best For |
|---------|-----------|----------|
| [Sequential Pipeline](#1-sequential-pipeline-claude--p) | Low | Daily dev steps, scripted workflows |
| [NanoClaw REPL](#2-nanoclaw-repl) | Low | Interactive persistent sessions |
| [Infinite Agentic Loop](#3-infinite-agentic-loop) | Medium | Parallel content generation, spec-driven work |
| [Continuous Claude PR Loop](#4-continuous-claude-pr-loop) | Medium | Multi-day iterative projects with CI gates |
| [De-Sloppify Pattern](#5-the-de-sloppify-pattern) | Add-on | Quality cleanup after any Implementer step |
| [Ralphinho / RFC-Driven DAG](#6-ralphinho--rfc-driven-dag-orchestration) | High | Large features, multi-unit parallel work with merge queue |
---
## 1. Sequential Pipeline (`claude -p`)
**The simplest loop.** Break daily development into a sequence of non-interactive `claude -p` calls. Each call is a focused step with a clear prompt.
### Core Insight
> If you can't figure out a loop like this, it means you can't even drive the LLM to fix your code in interactive mode.
The `claude -p` flag runs Claude Code non-interactively with a prompt, exits when done. Chain calls to build a pipeline:
```bash
#!/bin/bash
# daily-dev.sh — Sequential pipeline for a feature branch
set -e
# Step 1: Implement the feature
claude -p "Read the spec in docs/auth-spec.md. Implement OAuth2 login in src/auth/. Write tests first (TDD). Do NOT create any new documentation files."
# Step 2: De-sloppify (cleanup pass)
claude -p "Review all files changed by the previous commit. Remove any unnecessary type tests, overly defensive checks, or testing of language features (e.g., testing that TypeScript generics work). Keep real business logic tests. Run the test suite after cleanup."
# Step 3: Verify
claude -p "Run the full build, lint, type check, and test suite. Fix any failures. Do not add new features."
# Step 4: Commit
claude -p "Create a conventional commit for all staged changes. Use 'feat: add OAuth2 login flow' as the message."
```
### Key Design Principles
1. **Each step is isolated** — A fresh context window per `claude -p` call means no context bleed between steps.
2. **Order matters** — Steps execute sequentially. Each builds on the filesystem state left by the previous.
3. **Negative instructions are dangerous** — Don't say "don't test type systems." Instead, add a separate cleanup step (see [De-Sloppify Pattern](#5-the-de-sloppify-pattern)).
4. **Exit codes propagate**`set -e` stops the pipeline on failure.
### Variations
**With model routing:**
```bash
# Research with Opus (deep reasoning)
claude -p --model opus "Analyze the codebase architecture and write a plan for adding caching..."
# Implement with Sonnet (fast, capable)
claude -p "Implement the caching layer according to the plan in docs/caching-plan.md..."
# Review with Opus (thorough)
claude -p --model opus "Review all changes for security issues, race conditions, and edge cases..."
```
**With environment context:**
```bash
# Pass context via files, not prompt length
echo "Focus areas: auth module, API rate limiting" > .claude-context.md
claude -p "Read .claude-context.md for priorities. Work through them in order."
rm .claude-context.md
```
**With `--allowedTools` restrictions:**
```bash
# Read-only analysis pass
claude -p --allowedTools "Read,Grep,Glob" "Audit this codebase for security vulnerabilities..."
# Write-only implementation pass
claude -p --allowedTools "Read,Write,Edit,Bash" "Implement the fixes from security-audit.md..."
```
---
## 2. NanoClaw REPL
**ECC's built-in persistent loop.** A session-aware REPL that calls `claude -p` synchronously with full conversation history.
```bash
# Start the default session
node scripts/claw.js
# Named session with skill context
CLAW_SESSION=my-project CLAW_SKILLS=tdd-workflow,security-review node scripts/claw.js
```
### How It Works
1. Loads conversation history from `~/.claude/claw/{session}.md`
2. Each user message is sent to `claude -p` with full history as context
3. Responses are appended to the session file (Markdown-as-database)
4. Sessions persist across restarts
### When NanoClaw vs Sequential Pipeline
| Use Case | NanoClaw | Sequential Pipeline |
|----------|----------|-------------------|
| Interactive exploration | Yes | No |
| Scripted automation | No | Yes |
| Session persistence | Built-in | Manual |
| Context accumulation | Grows per turn | Fresh each step |
| CI/CD integration | Poor | Excellent |
See the `/claw` command documentation for full details.
---
## 3. Infinite Agentic Loop
**A two-prompt system** that orchestrates parallel sub-agents for specification-driven generation. Developed by disler (credit: @disler).
### Architecture: Two-Prompt System
```
PROMPT 1 (Orchestrator) PROMPT 2 (Sub-Agents)
┌─────────────────────┐ ┌──────────────────────┐
│ Parse spec file │ │ Receive full context │
│ Scan output dir │ deploys │ Read assigned number │
│ Plan iteration │────────────│ Follow spec exactly │
│ Assign creative dirs │ N agents │ Generate unique output │
│ Manage waves │ │ Save to output dir │
└─────────────────────┘ └──────────────────────┘
```
### The Pattern
1. **Spec Analysis** — Orchestrator reads a specification file (Markdown) defining what to generate
2. **Directory Recon** — Scans existing output to find the highest iteration number
3. **Parallel Deployment** — Launches N sub-agents, each with:
- The full spec
- A unique creative direction
- A specific iteration number (no conflicts)
- A snapshot of existing iterations (for uniqueness)
4. **Wave Management** — For infinite mode, deploys waves of 3-5 agents until context is exhausted
### Implementation via Claude Code Commands
Create `.claude/commands/infinite.md`:
```markdown
Parse the following arguments from $ARGUMENTS:
1. spec_file — path to the specification markdown
2. output_dir — where iterations are saved
3. count — integer 1-N or "infinite"
PHASE 1: Read and deeply understand the specification.
PHASE 2: List output_dir, find highest iteration number. Start at N+1.
PHASE 3: Plan creative directions — each agent gets a DIFFERENT theme/approach.
PHASE 4: Deploy sub-agents in parallel (Task tool). Each receives:
- Full spec text
- Current directory snapshot
- Their assigned iteration number
- Their unique creative direction
PHASE 5 (infinite mode): Loop in waves of 3-5 until context is low.
```
**Invoke:**
```bash
/project:infinite specs/component-spec.md src/ 5
/project:infinite specs/component-spec.md src/ infinite
```
### Batching Strategy
| Count | Strategy |
|-------|----------|
| 1-5 | All agents simultaneously |
| 6-20 | Batches of 5 |
| infinite | Waves of 3-5, progressive sophistication |
### Key Insight: Uniqueness via Assignment
Don't rely on agents to self-differentiate. The orchestrator **assigns** each agent a specific creative direction and iteration number. This prevents duplicate concepts across parallel agents.
---
## 4. Continuous Claude PR Loop
**A production-grade shell script** that runs Claude Code in a continuous loop, creating PRs, waiting for CI, and merging automatically. Created by AnandChowdhary (credit: @AnandChowdhary).
### Core Loop
```
┌─────────────────────────────────────────────────────┐
│ CONTINUOUS CLAUDE ITERATION │
│ │
│ 1. Create branch (continuous-claude/iteration-N) │
│ 2. Run claude -p with enhanced prompt │
│ 3. (Optional) Reviewer pass — separate claude -p │
│ 4. Commit changes (claude generates message) │
│ 5. Push + create PR (gh pr create) │
│ 6. Wait for CI checks (poll gh pr checks) │
│ 7. CI failure? → Auto-fix pass (claude -p) │
│ 8. Merge PR (squash/merge/rebase) │
│ 9. Return to main → repeat │
│ │
│ Limit by: --max-runs N | --max-cost $X │
│ --max-duration 2h | completion signal │
└─────────────────────────────────────────────────────┘
```
### Installation
```bash
curl -fsSL https://raw.githubusercontent.com/AnandChowdhary/continuous-claude/HEAD/install.sh | bash
```
### Usage
```bash
# Basic: 10 iterations
continuous-claude --prompt "Add unit tests for all untested functions" --max-runs 10
# Cost-limited
continuous-claude --prompt "Fix all linter errors" --max-cost 5.00
# Time-boxed
continuous-claude --prompt "Improve test coverage" --max-duration 8h
# With code review pass
continuous-claude \
--prompt "Add authentication feature" \
--max-runs 10 \
--review-prompt "Run npm test && npm run lint, fix any failures"
# Parallel via worktrees
continuous-claude --prompt "Add tests" --max-runs 5 --worktree tests-worker &
continuous-claude --prompt "Refactor code" --max-runs 5 --worktree refactor-worker &
wait
```
### Cross-Iteration Context: SHARED_TASK_NOTES.md
The critical innovation: a `SHARED_TASK_NOTES.md` file persists across iterations:
```markdown
## Progress
- [x] Added tests for auth module (iteration 1)
- [x] Fixed edge case in token refresh (iteration 2)
- [ ] Still need: rate limiting tests, error boundary tests
## Next Steps
- Focus on rate limiting module next
- The mock setup in tests/helpers.ts can be reused
```
Claude reads this file at iteration start and updates it at iteration end. This bridges the context gap between independent `claude -p` invocations.
### CI Failure Recovery
When PR checks fail, Continuous Claude automatically:
1. Fetches the failed run ID via `gh run list`
2. Spawns a new `claude -p` with CI fix context
3. Claude inspects logs via `gh run view`, fixes code, commits, pushes
4. Re-waits for checks (up to `--ci-retry-max` attempts)
### Completion Signal
Claude can signal "I'm done" by outputting a magic phrase:
```bash
continuous-claude \
--prompt "Fix all bugs in the issue tracker" \
--completion-signal "CONTINUOUS_CLAUDE_PROJECT_COMPLETE" \
--completion-threshold 3 # Stops after 3 consecutive signals
```
Three consecutive iterations signaling completion stops the loop, preventing wasted runs on finished work.
### Key Configuration
| Flag | Purpose |
|------|---------|
| `--max-runs N` | Stop after N successful iterations |
| `--max-cost $X` | Stop after spending $X |
| `--max-duration 2h` | Stop after time elapsed |
| `--merge-strategy squash` | squash, merge, or rebase |
| `--worktree <name>` | Parallel execution via git worktrees |
| `--disable-commits` | Dry-run mode (no git operations) |
| `--review-prompt "..."` | Add reviewer pass per iteration |
| `--ci-retry-max N` | Auto-fix CI failures (default: 1) |
---
## 5. The De-Sloppify Pattern
**An add-on pattern for any loop.** Add a dedicated cleanup/refactor step after each Implementer step.
### The Problem
When you ask an LLM to implement with TDD, it takes "write tests" too literally:
- Tests that verify TypeScript's type system works (testing `typeof x === 'string'`)
- Overly defensive runtime checks for things the type system already guarantees
- Tests for framework behavior rather than business logic
- Excessive error handling that obscures the actual code
### Why Not Negative Instructions?
Adding "don't test type systems" or "don't add unnecessary checks" to the Implementer prompt has downstream effects:
- The model becomes hesitant about ALL testing
- It skips legitimate edge case tests
- Quality degrades unpredictably
### The Solution: Separate Pass
Instead of constraining the Implementer, let it be thorough. Then add a focused cleanup agent:
```bash
# Step 1: Implement (let it be thorough)
claude -p "Implement the feature with full TDD. Be thorough with tests."
# Step 2: De-sloppify (separate context, focused cleanup)
claude -p "Review all changes in the working tree. Remove:
- Tests that verify language/framework behavior rather than business logic
- Redundant type checks that the type system already enforces
- Over-defensive error handling for impossible states
- Console.log statements
- Commented-out code
Keep all business logic tests. Run the test suite after cleanup to ensure nothing breaks."
```
### In a Loop Context
```bash
for feature in "${features[@]}"; do
# Implement
claude -p "Implement $feature with TDD."
# De-sloppify
claude -p "Cleanup pass: review changes, remove test/code slop, run tests."
# Verify
claude -p "Run build + lint + tests. Fix any failures."
# Commit
claude -p "Commit with message: feat: add $feature"
done
```
### Key Insight
> Rather than adding negative instructions which have downstream quality effects, add a separate de-sloppify pass. Two focused agents outperform one constrained agent.
---
## 6. Ralphinho / RFC-Driven DAG Orchestration
**The most sophisticated pattern.** An RFC-driven, multi-agent pipeline that decomposes a spec into a dependency DAG, runs each unit through a tiered quality pipeline, and lands them via an agent-driven merge queue. Created by enitrat (credit: @enitrat).
### Architecture Overview
```
RFC/PRD Document
DECOMPOSITION (AI)
Break RFC into work units with dependency DAG
┌──────────────────────────────────────────────────────┐
│ RALPH LOOP (up to 3 passes) │
│ │
│ For each DAG layer (sequential, by dependency): │
│ │
│ ┌── Quality Pipelines (parallel per unit) ───────┐ │
│ │ Each unit in its own worktree: │ │
│ │ Research → Plan → Implement → Test → Review │ │
│ │ (depth varies by complexity tier) │ │
│ └────────────────────────────────────────────────┘ │
│ │
│ ┌── Merge Queue ─────────────────────────────────┐ │
│ │ Rebase onto main → Run tests → Land or evict │ │
│ │ Evicted units re-enter with conflict context │ │
│ └────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────┘
```
### RFC Decomposition
AI reads the RFC and produces work units:
```typescript
interface WorkUnit {
id: string; // kebab-case identifier
name: string; // Human-readable name
rfcSections: string[]; // Which RFC sections this addresses
description: string; // Detailed description
deps: string[]; // Dependencies (other unit IDs)
acceptance: string[]; // Concrete acceptance criteria
tier: "trivial" | "small" | "medium" | "large";
}
```
**Decomposition Rules:**
- Prefer fewer, cohesive units (minimize merge risk)
- Minimize cross-unit file overlap (avoid conflicts)
- Keep tests WITH implementation (never separate "implement X" + "test X")
- Dependencies only where real code dependency exists
The dependency DAG determines execution order:
```
Layer 0: [unit-a, unit-b] ← no deps, run in parallel
Layer 1: [unit-c] ← depends on unit-a
Layer 2: [unit-d, unit-e] ← depend on unit-c
```
### Complexity Tiers
Different tiers get different pipeline depths:
| Tier | Pipeline Stages |
|------|----------------|
| **trivial** | implement → test |
| **small** | implement → test → code-review |
| **medium** | research → plan → implement → test → PRD-review + code-review → review-fix |
| **large** | research → plan → implement → test → PRD-review + code-review → review-fix → final-review |
This prevents expensive operations on simple changes while ensuring architectural changes get thorough scrutiny.
### Separate Context Windows (Author-Bias Elimination)
Each stage runs in its own agent process with its own context window:
| Stage | Model | Purpose |
|-------|-------|---------|
| Research | Sonnet | Read codebase + RFC, produce context doc |
| Plan | Opus | Design implementation steps |
| Implement | Codex | Write code following the plan |
| Test | Sonnet | Run build + test suite |
| PRD Review | Sonnet | Spec compliance check |
| Code Review | Opus | Quality + security check |
| Review Fix | Codex | Address review issues |
| Final Review | Opus | Quality gate (large tier only) |
**Critical design:** The reviewer never wrote the code it reviews. This eliminates author bias — the most common source of missed issues in self-review.
### Merge Queue with Eviction
After quality pipelines complete, units enter the merge queue:
```
Unit branch
├─ Rebase onto main
│ └─ Conflict? → EVICT (capture conflict context)
├─ Run build + tests
│ └─ Fail? → EVICT (capture test output)
└─ Pass → Fast-forward main, push, delete branch
```
**File Overlap Intelligence:**
- Non-overlapping units land speculatively in parallel
- Overlapping units land one-by-one, rebasing each time
**Eviction Recovery:**
When evicted, full context is captured (conflicting files, diffs, test output) and fed back to the implementer on the next Ralph pass:
```markdown
## MERGE CONFLICT — RESOLVE BEFORE NEXT LANDING
Your previous implementation conflicted with another unit that landed first.
Restructure your changes to avoid the conflicting files/lines below.
{full eviction context with diffs}
```
### Data Flow Between Stages
```
research.contextFilePath ──────────────────→ plan
plan.implementationSteps ──────────────────→ implement
implement.{filesCreated, whatWasDone} ─────→ test, reviews
test.failingSummary ───────────────────────→ reviews, implement (next pass)
reviews.{feedback, issues} ────────────────→ review-fix → implement (next pass)
final-review.reasoning ────────────────────→ implement (next pass)
evictionContext ───────────────────────────→ implement (after merge conflict)
```
### Worktree Isolation
Every unit runs in an isolated worktree (uses jj/Jujutsu, not git):
```
/tmp/workflow-wt-{unit-id}/
```
Pipeline stages for the same unit **share** a worktree, preserving state (context files, plan files, code changes) across research → plan → implement → test → review.
### Key Design Principles
1. **Deterministic execution** — Upfront decomposition locks in parallelism and ordering
2. **Human review at leverage points** — The work plan is the single highest-leverage intervention point
3. **Separate concerns** — Each stage in a separate context window with a separate agent
4. **Conflict recovery with context** — Full eviction context enables intelligent re-runs, not blind retries
5. **Tier-driven depth** — Trivial changes skip research/review; large changes get maximum scrutiny
6. **Resumable workflows** — Full state persisted to SQLite; resume from any point
### When to Use Ralphinho vs Simpler Patterns
| Signal | Use Ralphinho | Use Simpler Pattern |
|--------|--------------|-------------------|
| Multiple interdependent work units | Yes | No |
| Need parallel implementation | Yes | No |
| Merge conflicts likely | Yes | No (sequential is fine) |
| Single-file change | No | Yes (sequential pipeline) |
| Multi-day project | Yes | Maybe (continuous-claude) |
| Spec/RFC already written | Yes | Maybe |
| Quick iteration on one thing | No | Yes (NanoClaw or pipeline) |
---
## Choosing the Right Pattern
### Decision Matrix
```
Is the task a single focused change?
├─ Yes → Sequential Pipeline or NanoClaw
└─ No → Is there a written spec/RFC?
├─ Yes → Do you need parallel implementation?
│ ├─ Yes → Ralphinho (DAG orchestration)
│ └─ No → Continuous Claude (iterative PR loop)
└─ No → Do you need many variations of the same thing?
├─ Yes → Infinite Agentic Loop (spec-driven generation)
└─ No → Sequential Pipeline with de-sloppify
```
### Combining Patterns
These patterns compose well:
1. **Sequential Pipeline + De-Sloppify** — The most common combination. Every implement step gets a cleanup pass.
2. **Continuous Claude + De-Sloppify** — Add `--review-prompt` with a de-sloppify directive to each iteration.
3. **Any loop + Verification** — Use ECC's `/verify` command or `verification-loop` skill as a gate before commits.
4. **Ralphinho's tiered approach in simpler loops** — Even in a sequential pipeline, you can route simple tasks to Haiku and complex tasks to Opus:
```bash
# Simple formatting fix
claude -p --model haiku "Fix the import ordering in src/utils.ts"
# Complex architectural change
claude -p --model opus "Refactor the auth module to use the strategy pattern"
```
---
## Anti-Patterns
### Common Mistakes
1. **Infinite loops without exit conditions** — Always have a max-runs, max-cost, max-duration, or completion signal.
2. **No context bridge between iterations** — Each `claude -p` call starts fresh. Use `SHARED_TASK_NOTES.md` or filesystem state to bridge context.
3. **Retrying the same failure** — If an iteration fails, don't just retry. Capture the error context and feed it to the next attempt.
4. **Negative instructions instead of cleanup passes** — Don't say "don't do X." Add a separate pass that removes X.
5. **All agents in one context window** — For complex workflows, separate concerns into different agent processes. The reviewer should never be the author.
6. **Ignoring file overlap in parallel work** — If two parallel agents might edit the same file, you need a merge strategy (sequential landing, rebase, or conflict resolution).
---
## References
| Project | Author | Link |
|---------|--------|------|
| Ralphinho | enitrat | credit: @enitrat |
| Infinite Agentic Loop | disler | credit: @disler |
| Continuous Claude | AnandChowdhary | credit: @AnandChowdhary |
| NanoClaw | ECC | `/claw` command in this repo |
| Verification Loop | ECC | `skills/verification-loop/` in this repo |

View File

@@ -161,6 +161,7 @@ include(FetchContent)
set(GTEST_VERSION v1.17.0) # Adjust to project policy.
FetchContent_Declare(
googletest
# Google Test framework (official repository)
URL https://github.com/google/googletest/archive/refs/tags/${GTEST_VERSION}.zip
)
FetchContent_MakeAvailable(googletest)

View File

@@ -8,7 +8,7 @@ origin: ECC
Create zero-dependency, animation-rich HTML presentations that run entirely in the browser.
Inspired by the visual exploration approach showcased in work by [zarazhangrui](https://github.com/zarazhangrui).
Inspired by the visual exploration approach showcased in work by zarazhangrui (credit: @zarazhangrui).
## When to Activate

View File

@@ -0,0 +1,196 @@
---
name: plankton-code-quality
description: "Write-time code quality enforcement using Plankton — auto-formatting, linting, and Claude-powered fixes on every file edit via hooks."
origin: community
---
# Plankton Code Quality Skill
Integration reference for Plankton (credit: @alxfazio), a write-time code quality enforcement system for Claude Code. Plankton runs formatters and linters on every file edit via PostToolUse hooks, then spawns Claude subprocesses to fix violations the agent didn't catch.
## When to Use
- You want automatic formatting and linting on every file edit (not just at commit time)
- You need defense against agents modifying linter configs to pass instead of fixing code
- You want tiered model routing for fixes (Haiku for simple style, Sonnet for logic, Opus for types)
- You work with multiple languages (Python, TypeScript, Shell, YAML, JSON, TOML, Markdown, Dockerfile)
## How It Works
### Three-Phase Architecture
Every time Claude Code edits or writes a file, Plankton's `multi_linter.sh` PostToolUse hook runs:
```
Phase 1: Auto-Format (Silent)
├─ Runs formatters (ruff format, biome, shfmt, taplo, markdownlint)
├─ Fixes 40-50% of issues silently
└─ No output to main agent
Phase 2: Collect Violations (JSON)
├─ Runs linters and collects unfixable violations
├─ Returns structured JSON: {line, column, code, message, linter}
└─ Still no output to main agent
Phase 3: Delegate + Verify
├─ Spawns claude -p subprocess with violations JSON
├─ Routes to model tier based on violation complexity:
│ ├─ Haiku: formatting, imports, style (E/W/F codes) — 120s timeout
│ ├─ Sonnet: complexity, refactoring (C901, PLR codes) — 300s timeout
│ └─ Opus: type system, deep reasoning (unresolved-attribute) — 600s timeout
├─ Re-runs Phase 1+2 to verify fixes
└─ Exit 0 if clean, Exit 2 if violations remain (reported to main agent)
```
### What the Main Agent Sees
| Scenario | Agent sees | Hook exit |
|----------|-----------|-----------|
| No violations | Nothing | 0 |
| All fixed by subprocess | Nothing | 0 |
| Violations remain after subprocess | `[hook] N violation(s) remain` | 2 |
| Advisory (duplicates, old tooling) | `[hook:advisory] ...` | 0 |
The main agent only sees issues the subprocess couldn't fix. Most quality problems are resolved transparently.
### Config Protection (Defense Against Rule-Gaming)
LLMs will modify `.ruff.toml` or `biome.json` to disable rules rather than fix code. Plankton blocks this with three layers:
1. **PreToolUse hook**`protect_linter_configs.sh` blocks edits to all linter configs before they happen
2. **Stop hook**`stop_config_guardian.sh` detects config changes via `git diff` at session end
3. **Protected files list**`.ruff.toml`, `biome.json`, `.shellcheckrc`, `.yamllint`, `.hadolint.yaml`, and more
### Package Manager Enforcement
A PreToolUse hook on Bash blocks legacy package managers:
- `pip`, `pip3`, `poetry`, `pipenv` → Blocked (use `uv`)
- `npm`, `yarn`, `pnpm` → Blocked (use `bun`)
- Allowed exceptions: `npm audit`, `npm view`, `npm publish`
## Setup
### Quick Start
```bash
# Clone Plankton into your project (or a shared location)
# Note: Plankton is by @alxfazio
git clone https://github.com/alexfazio/plankton.git
cd plankton
# Install core dependencies
brew install jaq ruff uv
# Install Python linters
uv sync --all-extras
# Start Claude Code — hooks activate automatically
claude
```
No install command, no plugin config. The hooks in `.claude/settings.json` are picked up automatically when you run Claude Code in the Plankton directory.
### Per-Project Integration
To use Plankton hooks in your own project:
1. Copy `.claude/hooks/` directory to your project
2. Copy `.claude/settings.json` hook configuration
3. Copy linter config files (`.ruff.toml`, `biome.json`, etc.)
4. Install the linters for your languages
### Language-Specific Dependencies
| Language | Required | Optional |
|----------|----------|----------|
| Python | `ruff`, `uv` | `ty` (types), `vulture` (dead code), `bandit` (security) |
| TypeScript/JS | `biome` | `oxlint`, `semgrep`, `knip` (dead exports) |
| Shell | `shellcheck`, `shfmt` | — |
| YAML | `yamllint` | — |
| Markdown | `markdownlint-cli2` | — |
| Dockerfile | `hadolint` (>= 2.12.0) | — |
| TOML | `taplo` | — |
| JSON | `jaq` | — |
## Pairing with ECC
### Complementary, Not Overlapping
| Concern | ECC | Plankton |
|---------|-----|----------|
| Code quality enforcement | PostToolUse hooks (Prettier, tsc) | PostToolUse hooks (20+ linters + subprocess fixes) |
| Security scanning | AgentShield, security-reviewer agent | Bandit (Python), Semgrep (TypeScript) |
| Config protection | — | PreToolUse blocks + Stop hook detection |
| Package manager | Detection + setup | Enforcement (blocks legacy PMs) |
| CI integration | — | Pre-commit hooks for git |
| Model routing | Manual (`/model opus`) | Automatic (violation complexity → tier) |
### Recommended Combination
1. Install ECC as your plugin (agents, skills, commands, rules)
2. Add Plankton hooks for write-time quality enforcement
3. Use AgentShield for security audits
4. Use ECC's verification-loop as a final gate before PRs
### Avoiding Hook Conflicts
If running both ECC and Plankton hooks:
- ECC's Prettier hook and Plankton's biome formatter may conflict on JS/TS files
- Resolution: disable ECC's Prettier PostToolUse hook when using Plankton (Plankton's biome is more comprehensive)
- Both can coexist on different file types (ECC handles what Plankton doesn't cover)
## Configuration Reference
Plankton's `.claude/hooks/config.json` controls all behavior:
```json
{
"languages": {
"python": true,
"shell": true,
"yaml": true,
"json": true,
"toml": true,
"dockerfile": true,
"markdown": true,
"typescript": {
"enabled": true,
"js_runtime": "auto",
"biome_nursery": "warn",
"semgrep": true
}
},
"phases": {
"auto_format": true,
"subprocess_delegation": true
},
"subprocess": {
"tiers": {
"haiku": { "timeout": 120, "max_turns": 10 },
"sonnet": { "timeout": 300, "max_turns": 10 },
"opus": { "timeout": 600, "max_turns": 15 }
},
"volume_threshold": 5
}
}
```
**Key settings:**
- Disable languages you don't use to speed up hooks
- `volume_threshold` — violations > this count auto-escalate to a higher model tier
- `subprocess_delegation: false` — skip Phase 3 entirely (just report violations)
## Environment Overrides
| Variable | Purpose |
|----------|---------|
| `HOOK_SKIP_SUBPROCESS=1` | Skip Phase 3, report violations directly |
| `HOOK_SUBPROCESS_TIMEOUT=N` | Override tier timeout |
| `HOOK_DEBUG_MODEL=1` | Log model selection decisions |
| `HOOK_SKIP_PM=1` | Bypass package manager enforcement |
## References
- Plankton (credit: @alxfazio)
- Plankton REFERENCE.md — Full architecture documentation (credit: @alxfazio)
- Plankton SETUP.md — Detailed installation guide (credit: @alxfazio)

View File

@@ -144,4 +144,4 @@ SELECT pg_reload_conf();
---
*Based on [Supabase Agent Skills](https://github.com/supabase/agent-skills) (MIT License)*
*Based on Supabase Agent Skills (credit: Supabase team) (MIT License)*

View File

@@ -136,7 +136,7 @@ Default to Sonnet for 90% of coding tasks. Upgrade to Opus when first attempt fa
Replace grep with mgrep - ~50% token reduction on average compared to traditional grep or ripgrep:
![mgrep Benchmark](./assets/images/longform/06-mgrep-benchmark.png)
*In our 50-task benchmark, mgrep + Claude Code used ~2x fewer tokens than grep-based workflows at similar or better judged quality. Source: https://github.com/mixedbread-ai/mgrep*
*In our 50-task benchmark, mgrep + Claude Code used ~2x fewer tokens than grep-based workflows at similar or better judged quality. Source: mgrep by @mixedbread-ai*
**Modular Codebase Benefits:**

View File

@@ -162,6 +162,7 @@ Plugins package tools for easy installation instead of tedious manual setup. A p
```bash
# Add a marketplace
# mgrep plugin by @mixedbread-ai
claude plugin marketplace add https://github.com/mixedbread-ai/mgrep
# Open Claude, run /plugins, find new marketplace, install from there