# ADR-001: Awesome Claude Code Community Resource Integration Strategy

**Date:** 2026-03-29
**Status:** Accepted
**Deciders:** @cwarner (project owner)

## Context

The [awesome-claude-code](https://github.com/hesreallyhim/awesome-claude-code) repository catalogs 200+ community tools, skills, workflows, and resources for Claude Code. A comprehensive evaluation was conducted against harness-engineering's existing capabilities across 12 dimensions (orchestration, hooks, sessions, usage tracking, context priming, config management, container support, multi-platform, voice, config validation, graph visualization, and prompt injection defense).

The evaluation revealed:

- **8 high-value resources** that fill genuine gaps (security, safety, DX)
- **7 pattern-inspiration resources** worth studying for architectural ideas
- **5 nice-to-have resources** with low effort and real value
- **6 competitive intelligence resources** to track
- **~175+ resources** that are either already covered by harness, wrong category, or cosmetic

Key gaps identified:

1. **No prompt injection defense** — harness processes external input (issues, PRs, Slack) with no scanning
2. **No container sandboxing** — `sandboxPolicy` config exists but has no implementation
3. **Token tracking without cost calculation** — incomplete observability
4. **No CLAUDE.md/agent config validation** — despite generating these files
5. **No Claude Code hook SDK** — workspace hooks exist but no authoring support

## Decision

Adopt a **three-wave integration strategy** prioritizing security and safety, followed by developer experience, then pattern mining. Resources will be studied and patterns adapted to harness's native architecture rather than added as direct dependencies where possible.

### Wave 1 — Security & Safety (Priority: Immediate)

| Resource                                                                   | Action                   | Integration Path                                                                                                                                                                                     |
| -------------------------------------------------------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **[parry](https://github.com/vaporif/parry)**                              | Study + Build Native     | Analyze AST-based prompt injection scanning. Build `harness:prompt-guard` skill that scans MCP inputs, issue bodies, and PR descriptions before agent processing.                                    |
| **[Container Use](https://github.com/dagger/container-use)** (Dagger)      | Evaluate for Integration | Assess as sandbox backend for orchestrator's `sandboxPolicy`. Dagger is production-grade with good API surface. If viable, implement `ContainerBackend` alongside existing `ClaudeBackend`.          |
| **[Trail of Bits Security Skills](https://github.com/trailofbits/skills)** | Study + Adapt            | Analyze their security checklist patterns, vulnerability categories, and skill structure. Enhance `harness:security-scan` with their techniques. Adapt highest-value skills to harness skill format. |
| **[Dippy](https://github.com/ldayton/Dippy)**                              | Study                    | Analyze AST-based bash command safety analysis. Evaluate for orchestrator's command approval pipeline (currently regex-based).                                                                       |

### Wave 2 — Developer Experience (Priority: Next)

| Resource                                                                                                   | Action               | Integration Path                                                                                                                                                                                |
| ---------------------------------------------------------------------------------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **[ccflare](https://github.com/snipeship/ccflare)** / **[CC Usage](https://github.com/ryoppippi/ccusage)** | Study + Build Native | Add cost multipliers to `TokenUsage` type. Build `harness usage` CLI command that reads token events from sessions and calculates spend by model.                                               |
| **[agnix](https://github.com/agent-sh/agnix)**                                                             | Evaluate             | Assess as dev dependency for linting `.claude/` directory structure, CLAUDE.md files, and skill.yaml files. If too heavy, extract key validation rules into `harness validate --agent-configs`. |
| **[claude-hooks](https://github.com/johnlindquist/claude-hooks)**                                          | Study + Build Native | Analyze their TypeScript hook framework. Build `harness generate hooks` command that scaffolds typed Claude Code hooks for common patterns (pre-commit validation, notification, TDD guard).    |
| **[TDD Guard](https://github.com/nizos/tdd-guard)**                                                        | Study                | Analyze file-watching enforcement mechanism. Enhance `harness:tdd` skill with optional hook-based guard mode.                                                                                   |

### Wave 3 — Pattern Mining (Priority: Ongoing)

| Resource                                                                                   | What to Extract                                            |
| ------------------------------------------------------------------------------------------ | ---------------------------------------------------------- |
| **[Context Engineering Kit](https://github.com/NeoLabHQ/context-engineering-kit)**         | Token-efficiency techniques for `gather_context`           |
| **[Compound Engineering Plugin](https://github.com/EveryInc/compound-engineering-plugin)** | Error-to-lesson pipeline patterns for learnings store      |
| **[Superpowers](https://github.com/obra/superpowers)**                                     | Agent capability decomposition model                       |
| **[RIPER Workflow](https://github.com/tony/claude-code-riper-5)**                          | Phase gate design comparison with autopilot                |
| **[ContextKit](https://github.com/FlineDev/ContextKit)**                                   | Quality-gate approach comparison                           |
| **[CC Notify](https://github.com/dazuiba/CCNotify)**                                       | Desktop notification patterns for long-running operations  |
| **[recall](https://github.com/zippoxer/recall)**                                           | Full-text session search TUI for `harness sessions search` |

### Competitive Tracking (No Action — Monitor Only)

- **Claude Squad** — Multi-agent terminal orchestration
- **Claude Task Master** — Lightweight task management
- **Claude Code Flow** — Code-first orchestration
- **SuperClaude** — Cognitive persona framework
- **claudekit** — CLI toolkit with checkpointing
- **sudocode** — Spec-driven orchestration

### Explicitly Excluded

- **Status lines** (5 tools) — Cosmetic; harness is a framework, not a theme
- **Ralph Wiggum** (6 tools) — Harness autopilot provides better-guarded autonomous loops
- **Language-specific CLAUDE.md files** — Harness templates already generate these
- **Alternative clients** — Different product category
- **Voice/speech** — Not aligned with developer tooling focus
- **Most slash commands** (~40) — Harness's 79 skills supersede individual commands

## Alternatives Considered

### Option B: DX-First Wave

Lead with developer experience (cost tracking, config linting, hook authoring, notifications) before security. Rejected because harness's core identity is "mechanical enforcement" — having no security constraints on its own inputs undermines credibility. DX improvements are Wave 2, not abandoned.

### Option C: Pure Pattern Mining (No External Integration)

Study all resources but build everything from scratch natively. Rejected as unnecessarily slow for cases where external tools are production-grade (especially Dagger for container sandboxing). Adopted selectively — most items will be studied and rebuilt natively, but Container Use may warrant direct integration.

## Consequences

### Positive

- Closes the two highest-severity gaps (prompt injection, container sandboxing)
- Strengthens harness's core differentiator (security/safety enforcement)
- Cost tracking gives users budget visibility they currently lack
- Agent config validation prevents broken configs from shipping
- Pattern mining improves existing skills without adding dependencies

### Negative

- Wave 1 security work is less visible to end users — slower perceived progress
  - _Mitigation:_ Ship Wave 2 items concurrently where independent
- Container Use (Dagger) integration adds an external dependency
  - _Mitigation:_ Evaluate thoroughly; fall back to native implementation if Dagger is too heavy
- 8-12 week total timeline across all waves
  - _Mitigation:_ Waves are independent; can reprioritize based on feedback

### Neutral

- ~175 resources explicitly excluded — this is expected; most community tools target individual developers, not framework builders
- Competitive tracking list may grow as ecosystem evolves

## Action Items

### Wave 1 — Security & Safety

- [ ] Deep-dive **parry** — analyze scanning approach, identify adaptation points — owner: @cwarner — by: 2026-04-05
- [ ] Deep-dive **Container Use** — evaluate Dagger API, prototype `ContainerBackend` — owner: @cwarner — by: 2026-04-12
- [ ] Deep-dive **Trail of Bits skills** — catalog their checklist patterns, identify top 5 to adapt — owner: @cwarner — by: 2026-04-12
- [ ] Deep-dive **Dippy** — analyze AST parser, evaluate for orchestrator command approval — owner: @cwarner — by: 2026-04-05
- [ ] Spec `harness:prompt-guard` skill based on parry analysis — owner: @cwarner — by: 2026-04-19
- [ ] Implement orchestrator sandbox backend (Dagger or native) — owner: @cwarner — by: 2026-04-26

### Wave 2 — Developer Experience

- [ ] Add cost multipliers to `TokenUsage` and `harness usage` CLI command — owner: @cwarner — by: 2026-05-03
- [ ] Evaluate **agnix** as dev dependency or extract rules — owner: @cwarner — by: 2026-05-03
- [ ] Spec `harness generate hooks` command based on claude-hooks analysis — owner: @cwarner — by: 2026-05-10
- [ ] Enhance `harness:tdd` with guard mode based on TDD Guard patterns — owner: @cwarner — by: 2026-05-17

### Wave 3 — Pattern Mining

- [ ] Read and extract patterns from Context Engineering Kit — owner: @cwarner — ongoing
- [ ] Read and extract patterns from Compound Engineering Plugin — owner: @cwarner — ongoing
- [ ] Read and extract patterns from Superpowers — owner: @cwarner — ongoing
- [ ] Prototype `harness sessions search` based on recall patterns — owner: @cwarner — by: 2026-05-24
