intents-plugin

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# Intents Plugin for Claude Code

> **Warning**: This plugin is experimental and under active development. Expect breaking changes.

A plugin that keeps Claude Code agents in the context "smart zone" through chunked planning, sub-agent orchestration, and shared memory.

Inspired by [Dex Horthy's R-P-I workflow](https://www.youtube.com/watch?v=rmvDxxNubIg).
Kudos to [Matt Pocock for the Kanban Inspiration](https://x.com/mattpocockuk/status/2008200878633931247?s=20)

## The Problem

Building complex features with AI agents means managing context. When your context window fills up, it's game over—you lose continuity, the agent loses track of what it was doing, and you're stuck manually piecing things back together. Performance also degrades well before hitting limits (the "dumb zone" after ~40% context usage).

This plugin solves context management for long-running implementations:

1. **Chunked implementation** - Plans break work into context-sized pieces
2. **Sub-agent orchestration** - Research, reviews, and implementation run in isolated contexts
3. **Shared memory** - `MEMORY.md` tracks progress across sub-agents and sessions

## Design Philosophy

### Why Human-in-the-Loop?

AI coding harnesses exist on a spectrum from fully autonomous to fully manual. This plugin sits toward the "human drives, agents execute" end.

Fully autonomous approaches (like [Ralph](https://github.com/frankbria/ralph-claude-code)) are appealing—"fire and forget" sounds great. But they require pre-authorizing actions (via `--allowed-tools` or similar), and their safety mechanisms guard against different threats:

| What autonomous loops guard against | What they don't guard against |
|-------------------------------------|-------------------------------|
| Runaway iterations (max retries) | Model confusion compounding |
| API cost spikes (rate limits) | Wrong abstractions accumulating |
| Session timeouts (5hr detection) | Drift from original intent |
| Stagnation (no-change detection) | Subtle bugs building up |

**This plugin takes a different stance:** The metric isn't "my agent ran for 3 days"—it's "my agent built what I intended." The failure mode isn't Claude stopping; it's Claude continuing while quality degrades. Phase gates catch drift early, before it compounds.

More importantly, human-in-the-loop isn't about hitting enter. It's about spending your time on high-value work—designing systems, making architectural decisions, thinking through edge cases—while agents handle implementation. The workflow pipelines naturally: while agents implement Feature A, you're designing Feature B. Your bottleneck shifts from "writing code" to "thinking clearly about what to build."

### When Autonomous Makes Sense

- Well-defined, mechanical tasks (migrations, formatting, repetitive refactors)
- Tasks where "good enough" is acceptable
- When you'll review everything at the end anyway

### When Orchestrated Makes Sense

- Features requiring judgment calls
- Unfamiliar codebases where drift is costly
- When you want to catch problems early, not at the end

For a deeper dive on harness engineering, see [Taming the Beast](https://mattquinn.ca/journal/taming-the-beast).

## Installation

### Option 1: Plugin Mode (Recommended)

Load the plugin using the `--plugin-dir` flag:

```bash
cd /path/to/your/project
claude --plugin-dir /path/to/intents-plugin
```

Commands are namespaced: `/intents:plan`, `/intents:implement`, etc.

### Option 2: Standalone Mode

Symlink contents into your project's `.claude/` directory:

```bash
mkdir -p /path/to/your/project/.claude
ln -s /path/to/intents-plugin/commands /path/to/your/project/.claude/commands
ln -s /path/to/intents-plugin/agents /path/to/your/project/.claude/agents
ln -s /path/to/intents-plugin/skills /path/to/your/project/.claude/skills
```

Commands are unprefixed: `/plan`, `/implement`, etc.

**Note:** Standalone mode may conflict with existing `.claude/` configurations.

## Quick Start

### 1. Plan a feature

```
/intents:plan user-preferences
```

This runs the full R-P workflow:
- **Brainstorm** - Conversational loop to pull detail out and challenge vagueness
- **Research** - Explore codebase for patterns and fit
- **Refine** - Multi-lens critique of the chosen direction (code review, security, pragmatist, YAGNI, design)
- **Plan** - Create PLAN.md with chunks and dependency graph

**Skip options:**
```
/intents:plan sorting --skip-brainstorm   # Idea already clear
/intents:plan sorting --skip-research     # Context known
```

### 2. Implement the feature

```
/intents:implement user-preferences
```

**You become the orchestrator.** The command:
- Reads the kanban in MEMORY.md (Ready/Blocked/Done)
- Spawns `chunk-worker` agents for Ready chunks
- Workers implement -> validate -> update kanban -> commit
- Pauses at phase gates for manual testing

**Parallel execution:** Spawn multiple chunk-workers for independent Ready chunks.

**Options:**
```
/intents:implement sorting --skip-review  # Skip code review stage
```

## Commands

| Command | Description |
|---------|-------------|
| `/intents:plan <feature>` | Run R-P workflow, create plan |
| `/intents:implement <feature>` | Implement with chunk tracking |

### Command Options

**`/intents:plan`**
- `--skip-brainstorm` - Skip ideation (idea already clear)
- `--skip-research` - Skip codebase/tech research

**`/intents:implement`**
- `--skip-review` - Skip code review

## Workflow Overview

```
     +------------------+
     | /intents:plan    |
     | (Research-Plan)  |
     +--------+---------+
              |
              | Creates PLAN.md
              v
     +------------------+
     |/intents:implement|
     | (Implementation) |
     +--------+---------+
              |
              | Chunk by chunk
              | with validation
              v
     +------------------+
     | Feature Complete |
     +------------------+
```

## Agents Included

| Agent | Phase | Purpose |
|-------|-------|---------|
| `codebase-researcher` | Research | Explore internal codebase for context |
| `technical-researcher` | Research | Research external docs and APIs |
| `plan-critic` | Research | Multi-lens critique of the chosen direction (code review, security, pragmatist, YAGNI, design) |
| `feature-plan` | Plan | Create PLAN.md with dependency graph and test specs |
| `chunk-worker` | Implement | Stateless worker: implement -> validate -> update kanban -> commit |
| `code-reviewer` | Review | Validate code quality and patterns |
| `security-auditor` | Review | OWASP security review |
| `accessibility-reviewer` | Review | WCAG compliance check |

## Skills Included

| Skill | Purpose |
|-------|---------|
| `feature-brainstorm` | Conversational ideation loop - pulls detail, challenges vagueness |
| `design-system` | Auto-loads on UI files; reads project `DESIGN.md` if present, falls back to generic conventions |

## Plan Structure

When you run `/intents:plan`, it creates:

```
docs/plans/<feature>/
  PLAN.md    # Problem, goals, phases, chunks with dependencies
  MEMORY.md  # Kanban board (Ready/Blocked/Done) + session logs
```

### PLAN.md - Chunks with Dependencies

```
## Phase 1: Foundation
| Chunk | Size | Depends | Scope | Files |
|-------|------|---------|-------|-------|
| 1A | M | - | Types + config | 3 |
| 1B | S | - | Page route | 1 |
| 1C | M | 1A | Core component | 2 |
| 1D | S | 1A, 1B | Integration | 2 |
```

- `-` means no dependencies (can start immediately)
- Chunks with same/no dependencies can run **in parallel**

### MEMORY.md - Kanban Board

```markdown
## Kanban

### Ready
- **1A** (M): Types + config
- **1B** (S): Page route

### Blocked
- **1C** (M): Core component -> needs 1A
- **1D** (S): Integration -> needs 1A, 1B

### Done
(none yet)
```

Workers pick from Ready, move to Done, unblock dependents.

Each phase ends with a **phase gate** for manual testing.

## Directory Structure

```
intents-plugin/
  .claude-plugin/
    plugin.json           # Plugin manifest

  agents/                 # 10 specialized agents
    chunk-worker.md
    codebase-researcher.md
    code-reviewer.md
    ...

  skills/
    feature-brainstorm/SKILL.md

  commands/
    plan.md
    implement.md
    ccpp.md
    save-mem.md

  docs/                   # Research and plans
    plans/
    research/
```

## Best Practices

### When to use this plugin

- **Large features** that span multiple sessions
- **Complex implementations** that benefit from explicit planning
- **Team projects** where plans serve as documentation

### When NOT to use it

- **Quick fixes** - Just edit the code directly
- **Trivial features** - Overhead not worth it for small changes
- **Exploratory work** - R-P-I assumes you know what you're building

### Tips

1. **Review generated plans** - The planner makes educated guesses; correct any errors
2. **Use phase gates** - Don't skip manual testing between phases
3. **Trust the chunking** - Smaller chunks keep Claude in the smart zone

## Troubleshooting

### Feature not found

Either:
1. Run `/intents:plan <feature>` to create it
2. Check `docs/plans/` for existing plans

### Implementation stuck

Check `docs/plans/<feature>/MEMORY.md` for:
- Current chunk and progress
- Blockers logged
- Decisions made

Resume with `/intents:implement <feature>`.

## Background & Credits

This plugin is an experiment building a "harness" for AI coding agents, informed by:

**Dex Horthy's R-P-I Workflow (HumanLayer)** - The primary inspiration
- The "Dumb Zone": Performance degrades after ~40% context usage
- R-P-I pattern: Research -> Plan -> Implement in separate contexts
- Sub-agents as context isolation with compressed summaries
- Source: [No Vibes Allowed: Solving Hard Problems in Complex Codebases](https://www.youtube.com/watch?v=rmvDxxNubIg)

**Anthropic's Harness Research**
- Agents fail via over-ambition (run out of context) or premature victory (declare done too early)
- Initializer agent + coding agent pattern with progress tracking
- Source: [Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)

**Research on Context Limitations**
- Models degrade well before advertised limits (~130k effective for 200k windows)
- Working memory: LLMs track 5-10 variables before degrading
- Sources: [Context Rot (Chroma)](https://research.trychroma.com/context-rot), [Long Context Reasoning](https://nrehiew.github.io/blog/long_context/)

## Contributing

Improvements welcome:

1. Fork the repo
2. Create a feature branch
3. Use the plugin itself to plan and implement changes
4. Submit a PR

## License

MIT

Intents Plugin for Claude Code

Warning: This plugin is experimental and under active development. Expect breaking changes.

A plugin that keeps Claude Code agents in the context "smart zone" through chunked planning, sub-agent orchestration, and shared memory.

Inspired by Dex Horthy's R-P-I workflow. Kudos to Matt Pocock for the Kanban Inspiration

The Problem

Building complex features with AI agents means managing context. When your context window fills up, it's game over—you lose continuity, the agent loses track of what it was doing, and you're stuck manually piecing things back together. Performance also degrades well before hitting limits (the "dumb zone" after ~40% context usage).

This plugin solves context management for long-running implementations:

Chunked implementation - Plans break work into context-sized pieces
Sub-agent orchestration - Research, reviews, and implementation run in isolated contexts
Shared memory - MEMORY.md tracks progress across sub-agents and sessions

Design Philosophy

Why Human-in-the-Loop?

AI coding harnesses exist on a spectrum from fully autonomous to fully manual. This plugin sits toward the "human drives, agents execute" end.

Fully autonomous approaches (like Ralph) are appealing—"fire and forget" sounds great. But they require pre-authorizing actions (via --allowed-tools or similar), and their safety mechanisms guard against different threats:

What autonomous loops guard against	What they don't guard against
Runaway iterations (max retries)	Model confusion compounding
API cost spikes (rate limits)	Wrong abstractions accumulating
Session timeouts (5hr detection)	Drift from original intent
Stagnation (no-change detection)	Subtle bugs building up

This plugin takes a different stance: The metric isn't "my agent ran for 3 days"—it's "my agent built what I intended." The failure mode isn't Claude stopping; it's Claude continuing while quality degrades. Phase gates catch drift early, before it compounds.

More importantly, human-in-the-loop isn't about hitting enter. It's about spending your time on high-value work—designing systems, making architectural decisions, thinking through edge cases—while agents handle implementation. The workflow pipelines naturally: while agents implement Feature A, you're designing Feature B. Your bottleneck shifts from "writing code" to "thinking clearly about what to build."

When Autonomous Makes Sense

Well-defined, mechanical tasks (migrations, formatting, repetitive refactors)
Tasks where "good enough" is acceptable
When you'll review everything at the end anyway

When Orchestrated Makes Sense

Features requiring judgment calls
Unfamiliar codebases where drift is costly
When you want to catch problems early, not at the end

For a deeper dive on harness engineering, see Taming the Beast.

Installation

Option 1: Plugin Mode (Recommended)

Load the plugin using the --plugin-dir flag:

cd /path/to/your/project
claude --plugin-dir /path/to/intents-plugin

Commands are namespaced: /intents:plan, /intents:implement, etc.

Option 2: Standalone Mode

Symlink contents into your project's .claude/ directory:

mkdir -p /path/to/your/project/.claude
ln -s /path/to/intents-plugin/commands /path/to/your/project/.claude/commands
ln -s /path/to/intents-plugin/agents /path/to/your/project/.claude/agents
ln -s /path/to/intents-plugin/skills /path/to/your/project/.claude/skills

Commands are unprefixed: /plan, /implement, etc.

Note: Standalone mode may conflict with existing .claude/ configurations.

Quick Start

1. Plan a feature

/intents:plan user-preferences

This runs the full R-P workflow:

Brainstorm - Conversational loop to pull detail out and challenge vagueness
Research - Explore codebase for patterns and fit
Refine - Multi-lens critique of the chosen direction (code review, security, pragmatist, YAGNI, design)
Plan - Create PLAN.md with chunks and dependency graph

Skip options:

/intents:plan sorting --skip-brainstorm   # Idea already clear
/intents:plan sorting --skip-research     # Context known

2. Implement the feature

/intents:implement user-preferences

You become the orchestrator. The command:

Reads the kanban in MEMORY.md (Ready/Blocked/Done)
Spawns chunk-worker agents for Ready chunks
Workers implement -> validate -> update kanban -> commit
Pauses at phase gates for manual testing

Parallel execution: Spawn multiple chunk-workers for independent Ready chunks.

Options:

/intents:implement sorting --skip-review  # Skip code review stage

Commands

Command	Description
`/intents:plan <feature>`	Run R-P workflow, create plan
`/intents:implement <feature>`	Implement with chunk tracking

Command Options

/intents:plan

--skip-brainstorm - Skip ideation (idea already clear)
--skip-research - Skip codebase/tech research

/intents:implement

--skip-review - Skip code review

Workflow Overview

     +------------------+
     | /intents:plan    |
     | (Research-Plan)  |
     +--------+---------+
              |
              | Creates PLAN.md
              v
     +------------------+
     |/intents:implement|
     | (Implementation) |
     +--------+---------+
              |
              | Chunk by chunk
              | with validation
              v
     +------------------+
     | Feature Complete |
     +------------------+

Agents Included

Agent	Phase	Purpose
`codebase-researcher`	Research	Explore internal codebase for context
`technical-researcher`	Research	Research external docs and APIs
`plan-critic`	Research	Multi-lens critique of the chosen direction (code review, security, pragmatist, YAGNI, design)
`feature-plan`	Plan	Create PLAN.md with dependency graph and test specs
`chunk-worker`	Implement	Stateless worker: implement -> validate -> update kanban -> commit
`code-reviewer`	Review	Validate code quality and patterns
`security-auditor`	Review	OWASP security review
`accessibility-reviewer`	Review	WCAG compliance check

Skills Included

Skill	Purpose
`feature-brainstorm`	Conversational ideation loop - pulls detail, challenges vagueness
`design-system`	Auto-loads on UI files; reads project `DESIGN.md` if present, falls back to generic conventions

Plan Structure

When you run /intents:plan, it creates:

docs/plans/<feature>/
  PLAN.md    # Problem, goals, phases, chunks with dependencies
  MEMORY.md  # Kanban board (Ready/Blocked/Done) + session logs

PLAN.md - Chunks with Dependencies

## Phase 1: Foundation
| Chunk | Size | Depends | Scope | Files |
|-------|------|---------|-------|-------|
| 1A | M | - | Types + config | 3 |
| 1B | S | - | Page route | 1 |
| 1C | M | 1A | Core component | 2 |
| 1D | S | 1A, 1B | Integration | 2 |

- means no dependencies (can start immediately)
Chunks with same/no dependencies can run in parallel

MEMORY.md - Kanban Board

## Kanban

### Ready
- **1A** (M): Types + config
- **1B** (S): Page route

### Blocked
- **1C** (M): Core component -> needs 1A
- **1D** (S): Integration -> needs 1A, 1B

### Done
(none yet)

Workers pick from Ready, move to Done, unblock dependents.

Each phase ends with a phase gate for manual testing.

Directory Structure

intents-plugin/
  .claude-plugin/
    plugin.json           # Plugin manifest

  agents/                 # 10 specialized agents
    chunk-worker.md
    codebase-researcher.md
    code-reviewer.md
    ...

  skills/
    feature-brainstorm/SKILL.md

  commands/
    plan.md
    implement.md
    ccpp.md
    save-mem.md

  docs/                   # Research and plans
    plans/
    research/

Best Practices

When to use this plugin

Large features that span multiple sessions
Complex implementations that benefit from explicit planning
Team projects where plans serve as documentation

When NOT to use it

Quick fixes - Just edit the code directly
Trivial features - Overhead not worth it for small changes
Exploratory work - R-P-I assumes you know what you're building

Tips

Review generated plans - The planner makes educated guesses; correct any errors
Use phase gates - Don't skip manual testing between phases
Trust the chunking - Smaller chunks keep Claude in the smart zone

Troubleshooting

Feature not found

Either:

Run /intents:plan <feature> to create it
Check docs/plans/ for existing plans

Implementation stuck

Check docs/plans/<feature>/MEMORY.md for:

Current chunk and progress
Blockers logged
Decisions made

Resume with /intents:implement <feature>.

Background & Credits

This plugin is an experiment building a "harness" for AI coding agents, informed by:

Dex Horthy's R-P-I Workflow (HumanLayer) - The primary inspiration

The "Dumb Zone": Performance degrades after ~40% context usage
R-P-I pattern: Research -> Plan -> Implement in separate contexts
Sub-agents as context isolation with compressed summaries
Source: No Vibes Allowed: Solving Hard Problems in Complex Codebases

Anthropic's Harness Research

Agents fail via over-ambition (run out of context) or premature victory (declare done too early)
Initializer agent + coding agent pattern with progress tracking
Source: Effective Harnesses for Long-Running Agents

Research on Context Limitations

Models degrade well before advertised limits (~130k effective for 200k windows)
Working memory: LLMs track 5-10 variables before degrading
Sources: Context Rot (Chroma), Long Context Reasoning

Contributing

Improvements welcome:

Fork the repo
Create a feature branch
Use the plugin itself to plan and implement changes
Submit a PR

License

MIT