Skip to content

Commit 14e4e5a

Browse files
mattthomps1mattthomps1
committed
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 47610ea commit 14e4e5a

9 files changed

Lines changed: 1202 additions & 0 deletions

‎.claude/settings.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{
2+
"enabledPlugins": {
3+
"compound-engineering@every-marketplace": true
4+
}
5+
}

‎docs/brainstorms/2026-02-13-documentation-workflow-brainstorm.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Documentation Workflow Brainstorm
2+
3+
**Date:** 2026-02-13
4+
**Status:** Ready for planning
5+
6+
## What We're Building
7+
8+
A `/workflows:document` command that automatically updates project documentation after a feature is implemented and reviewed. It fills the gap between code review and knowledge capture in the workflow chain:
9+
10+
```
11+
Research → Brainstorm → Plan → Work → Review → Document → Compound
12+
```
13+
14+
**Scope:** Full project documentation — README, CHANGELOG, API docs, user guides, and inline code docs. Not limited to the plugin itself.
15+
16+
## Why This Approach
17+
18+
The compound-engineering workflow chain currently has no step for updating user-facing documentation. After `/workflows:work` finishes implementation and `/workflows:review` validates the code, documentation updates are left as a manual afterthought. This creates a gap where features ship without corresponding docs.
19+
20+
A phased workflow command (not an agent) was chosen because:
21+
- It follows the established workflow pattern (phase-based, skill-loading, handoff points)
22+
- It fits naturally in the chain between Review and Compound
23+
- A single workflow is simpler to maintain than multiple specialist agents
24+
- The propose-then-confirm model gives users control without being tedious
25+
26+
## Key Decisions
27+
28+
1. **Form factor:** New workflow command (`/workflows:document`), not an agent
29+
2. **Chain position:** After Review, before Compound
30+
3. **Discovery method:** Git diff + chain docs (brainstorm/plan) for full context
31+
4. **Autonomy model:** Propose-then-confirm — analyze what needs updating, present a plan, get approval, then execute
32+
5. **Documentation scope:** Full project docs (README, CHANGELOG, API docs, user guides, inline code docs)
33+
34+
## Design
35+
36+
### Phase 1: Discovery
37+
38+
Analyze the codebase to understand what was built and what docs need updating:
39+
40+
- **Git diff analysis:** Read the diff between current branch and main to identify what changed
41+
- **Chain doc lookup:** Find and read any brainstorm/plan documents for this feature (auto-detect from `docs/brainstorms/` and `docs/plans/` by date or topic)
42+
- **Doc inventory:** Scan the project for existing documentation files (README, CHANGELOG, API docs, guides, etc.)
43+
- **Gap analysis:** Compare what was built against what's documented
44+
45+
### Phase 2: Proposal
46+
47+
Present a structured proposal to the user:
48+
49+
- List each doc file that needs updating
50+
- For each file, describe what changes are needed (new section, updated section, new entry, etc.)
51+
- Flag any docs that should be created (e.g., "No API docs exist yet — should we create one?")
52+
- Use `AskUserQuestion` to get approval (approve all, select specific items, or skip)
53+
54+
### Phase 3: Execution
55+
56+
Make the approved documentation changes:
57+
58+
- Update each approved doc file
59+
- Follow existing doc conventions (detect style from existing content)
60+
- After all updates, show a summary of what was changed
61+
- Offer handoff to `/workflows:compound` for knowledge capture
62+
63+
## Open Questions
64+
65+
1. Should the workflow also update inline code comments/docstrings, or just standalone doc files?
66+
2. Should it create a documentation PR comment summarizing what was updated (useful for team visibility)?
67+
3. How should it handle projects with no existing docs — offer to scaffold a basic doc structure?

‎docs/brainstorms/2026-02-13-namespaced-extension-system-brainstorm.md‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
# Namespaced Extension System for Compound Engineering Plugin
2+
3+
**Date:** 2026-02-13
4+
**Status:** Brainstorm
5+
**Author:** Matthew Thompson
6+
7+
## What We're Building
8+
9+
A general extensibility system that lets users create optional plugins ("extensions") that work alongside the core compound-engineering plugin. Extensions follow a naming convention (`compound-engineering-<name>`) and are distributed through the same marketplace. They enable three categories of customization:
10+
11+
1. **Custom agents/skills** - Specialized agents and skills for specific domains (e.g., a Phoenix reviewer, a Terraform skill)
12+
2. **Framework packs** - Bundled sets of agents + skills + commands for a specific stack (e.g., "Rails Pack" with Rails-specific reviewers, generators, and conventions)
13+
3. **Convention configs** - Team/personal rules and style preferences delivered as curated CLAUDE.md snippets that influence how existing core agents behave
14+
15+
## Why This Approach
16+
17+
We chose a **namespaced extension system** (Approach 2) over alternatives because:
18+
19+
- **Works within current Claude Code spec** - No custom fields or spec changes needed. The marketplace already supports multiple plugins (coding-tutor proves this).
20+
- **Convention over configuration** - Naming patterns (`compound-engineering-*`) and tags create clear relationships without formal dependency mechanisms.
21+
- **Seamless experience** - The primary success metric. Extensions should feel like a natural part of the core with no conflicts or configuration headaches.
22+
- **Upgradable** - Can graduate to a formal manifest system (Approach 3) later if the ecosystem grows large enough to need it.
23+
24+
### Rejected Alternatives
25+
26+
- **Flat plugin ecosystem** - Too loose. No way to signal which plugins complement the core. Users would have to guess.
27+
- **Pack manifest system** - Adds `extends` field not in the Claude Code spec. Premature complexity for current ecosystem size.
28+
29+
## Key Decisions
30+
31+
### 1. Naming Convention
32+
33+
All extensions use the pattern: `compound-engineering-<name>`
34+
35+
Examples:
36+
- `compound-engineering-rails` (Rails framework pack)
37+
- `compound-engineering-security` (security-focused agents)
38+
- `compound-engineering-every-conventions` (team convention config)
39+
40+
This makes extensions immediately identifiable and groups them naturally in marketplace listings.
41+
42+
### 2. Convention Configs via CLAUDE.md
43+
44+
Convention configs are plugins that ship curated CLAUDE.md instructions rather than (or in addition to) agents. Claude already reads CLAUDE.md files as context, so this is the most natural mechanism. No new infrastructure needed.
45+
46+
A convention config plugin structure:
47+
```
48+
plugins/compound-engineering-my-team/
49+
├── .claude-plugin/plugin.json
50+
├── CLAUDE.md # Team conventions that agents read
51+
└── README.md
52+
```
53+
54+
### 3. Discovery via Tags and Browse Command
55+
56+
- Extensions use a shared tag (e.g., `compound-engineering-extension`) in marketplace.json
57+
- A `/extensions` command (or similar) lets users browse available extensions with descriptions
58+
- The marketplace listing groups extensions visually
59+
60+
### 4. Distribution Through Same Marketplace
61+
62+
All extensions live in the same marketplace repo (`every-marketplace`). This provides:
63+
- One-stop browsing
64+
- Consistent quality (maintainers can review contributions)
65+
- Simple installation (`claude /plugin install compound-engineering-rails`)
66+
67+
### 5. No Formal Dependencies
68+
69+
Claude Code doesn't support plugin dependencies. Each extension must function independently - it can complement the core but shouldn't break without it. This is a platform constraint we accept.
70+
71+
### 6. Component Namespacing
72+
73+
To avoid name collisions between extensions:
74+
- Agents: prefix or suffix with pack name (e.g., `rails-model-reviewer` not just `reviewer`)
75+
- Skills: use descriptive names (e.g., `rails-generators` not just `generators`)
76+
- Commands: use pack prefix (e.g., `rails:scaffold` not just `scaffold`)
77+
78+
## Extension Categories
79+
80+
### Framework Packs
81+
A framework pack bundles domain-specific tooling for a technology stack.
82+
83+
Example: `compound-engineering-rails`
84+
```
85+
plugins/compound-engineering-rails/
86+
├── .claude-plugin/plugin.json
87+
├── CLAUDE.md # Rails conventions and preferences
88+
├── agents/
89+
│ ├── rails-model-reviewer.md
90+
│ ├── rails-migration-checker.md
91+
│ └── rails-performance-agent.md
92+
├── skills/
93+
│ └── rails-generators/SKILL.md
94+
└── README.md
95+
```
96+
97+
### Custom Agents/Skills
98+
Individual agents or skills for specific needs.
99+
100+
Example: `compound-engineering-security`
101+
```
102+
plugins/compound-engineering-security/
103+
├── .claude-plugin/plugin.json
104+
├── agents/
105+
│ ├── owasp-scanner.md
106+
│ └── dependency-auditor.md
107+
├── skills/
108+
│ └── threat-model/SKILL.md
109+
└── README.md
110+
```
111+
112+
### Convention Configs
113+
Team or personal preferences that shape agent behavior.
114+
115+
Example: `compound-engineering-every-conventions`
116+
```
117+
plugins/compound-engineering-every-conventions/
118+
├── .claude-plugin/plugin.json
119+
├── CLAUDE.md # Every's coding standards, style preferences, etc.
120+
└── README.md
121+
```
122+
123+
## Open Questions
124+
125+
1. **Quality control** - Should there be a review process for community-contributed extensions, or is it open contribution?
126+
2. **Versioning alignment** - Should extensions declare which version of the core they're designed for, even informally?
127+
3. **Starter template** - Should we provide a `/create-extension` command or template repo to scaffold new extensions?
128+
4. **Testing** - How do we verify extensions don't conflict with each other or the core?
129+
5. **Documentation** - Should the docs site auto-generate pages for extensions, or is README.md sufficient?
130+
131+
## Next Steps
132+
133+
- Plan the implementation: directory structure, marketplace.json changes, example extensions
134+
- Build 1-2 example extensions to validate the pattern
135+
- Create documentation for extension authors
136+
- Consider a `/create-extension` scaffolding command

‎docs/plans/2026-02-13-feat-documentation-workflow-plan.md‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
---
2+
title: "feat: Add documentation workflow command"
3+
type: feat
4+
date: 2026-02-13
5+
---
6+
7+
# feat: Add documentation workflow command
8+
9+
## Overview
10+
11+
Add a `/workflows:document` command that updates project documentation after a feature is implemented and reviewed. This fills the gap between `/workflows:review` and `/workflows:compound` in the workflow chain:
12+
13+
```
14+
Research → Brainstorm → Plan → Work → Review → Document → Compound
15+
```
16+
17+
**Brainstorm:** [docs/brainstorms/2026-02-13-documentation-workflow-brainstorm.md](../brainstorms/2026-02-13-documentation-workflow-brainstorm.md)
18+
19+
## Problem Statement
20+
21+
The workflow chain has no step for updating user-facing documentation. Features ship without corresponding doc updates because it's left as a manual afterthought. A structured, propose-then-confirm workflow would make documentation a natural part of the development cycle.
22+
23+
## Proposed Solution
24+
25+
A single workflow command file at `plugins/compound-engineering/commands/workflows/document.md` that follows the established phase-based pattern. Three phases: Discovery → Proposal → Execution.
26+
27+
## Implementation
28+
29+
### File to create
30+
31+
#### `plugins/compound-engineering/commands/workflows/document.md`
32+
33+
The workflow command. Structure:
34+
35+
```yaml
36+
---
37+
name: workflows:document
38+
description: Update project documentation after implementation and review
39+
argument-hint: "[optional: path to brainstorm or plan doc, or PR number]"
40+
---
41+
```
42+
43+
**Phase 1: Discovery**
44+
45+
Gather context about what was built and what docs exist:
46+
47+
1. **Determine diff base** — Check for PR (via `gh pr view`), fall back to `main`/`master`
48+
2. **Git diff analysis** — Run `git diff <base>...HEAD --stat` then read changed files to understand what was built. Filter out test files, generated code, and lock files to keep scope manageable
49+
3. **Chain doc lookup** — Search `docs/brainstorms/` and `docs/plans/` for recent documents matching the current feature (by date, branch name, or topic). If `$ARGUMENTS` provides a path, use that directly. If nothing found, proceed with diff-only mode
50+
4. **Doc inventory** — Use Glob to find existing documentation files: `README*`, `CHANGELOG*`, `docs/**/*.md`, `API.md`, `GUIDE.md`, any `**/README.md` in subdirectories. Note their last-modified dates and sizes
51+
5. **Gap analysis** — Compare what was built (from diff + chain docs) against what's documented. Identify: new features not mentioned in README, missing CHANGELOG entry, outdated API docs, new public APIs without docstrings
52+
53+
**Phase 2: Proposal**
54+
55+
Present a structured update plan to the user:
56+
57+
- For each doc file that needs changes, show: file path, what kind of update (new section, updated section, new entry), and a 1-line summary of the change
58+
- Flag any new docs that should be created (e.g., "No CHANGELOG exists — create one?")
59+
- Flag docs that might need deletion or archival (if features were removed)
60+
- Use `AskUserQuestion` with options:
61+
1. **Approve all** — Execute all proposed updates
62+
2. **Select items** — Choose which updates to apply (use multiSelect)
63+
3. **Skip documentation** — Exit without changes
64+
4. **Refine proposal** — Ask for adjustments
65+
66+
**Guardrails to prevent overwriting user content:**
67+
- Only modify sections relevant to the changed code — never rewrite entire files
68+
- When updating an existing section, show the diff preview before applying
69+
- Detect and preserve custom sections (anything not generated by this workflow)
70+
- For README: append new feature sections, don't restructure existing content
71+
72+
**Phase 3: Execution**
73+
74+
Make the approved changes:
75+
76+
1. For each approved update, read the target file, make the change, write it back
77+
2. Match existing doc style (detect heading levels, tone, formatting from surrounding content)
78+
3. For CHANGELOG: use Keep a Changelog format if one exists, otherwise detect existing format
79+
4. After all updates, show a summary: files changed, sections added/updated
80+
5. Offer handoff via `AskUserQuestion`:
81+
1. **Continue to `/workflows:compound`** — Document solved problems for team knowledge
82+
2. **Review changes** — Load `document-review` skill for quality pass
83+
3. **Done** — Documentation complete
84+
85+
### Edge cases to handle
86+
87+
- **No existing docs:** Offer to scaffold a minimal doc structure (README + CHANGELOG) rather than silently failing
88+
- **No git diff:** If on main with no changes, check `$ARGUMENTS` for a PR number. If nothing, tell the user and exit
89+
- **Doc-only changes in diff:** Detect and exit early — "Changes are documentation-only, nothing additional to document"
90+
- **Massive diffs (50+ files):** Summarize by directory/component rather than file-by-file. Focus on public API changes
91+
- **No chain docs found:** Proceed with diff-only mode, mention that brainstorm/plan context would improve results
92+
93+
### Files to update (plugin metadata)
94+
95+
After creating the command, update these files per the plugin's versioning requirements:
96+
97+
- [ ] `plugins/compound-engineering/.claude-plugin/plugin.json` — bump minor version, update command count in description
98+
- [ ] `.claude-plugin/marketplace.json` — update description with new command count
99+
- [ ] `plugins/compound-engineering/README.md` — add `/workflows:document` to commands list
100+
- [ ] `plugins/compound-engineering/CHANGELOG.md` — add entry under new version
101+
102+
### Optional: Update review workflow handoff
103+
104+
Update `plugins/compound-engineering/commands/workflows/review.md` to offer `/workflows:document` as a next step after review completes. Add an option in the final handoff section.
105+
106+
## Acceptance Criteria
107+
108+
- [ ] `/workflows:document` command exists and loads correctly
109+
- [ ] Phase 1 discovers changed files via git diff and finds chain docs when available
110+
- [ ] Phase 2 presents a clear proposal listing each doc update needed
111+
- [ ] User can approve all, select specific items, or skip
112+
- [ ] Phase 3 makes only approved changes without overwriting unrelated content
113+
- [ ] Handoff to `/workflows:compound` works
114+
- [ ] Plugin metadata (version, counts, changelog) updated correctly
115+
- [ ] Works in diff-only mode when no chain docs exist
116+
117+
## References
118+
119+
- Workflow pattern: `plugins/compound-engineering/commands/workflows/work.md`
120+
- Handoff pattern: `plugins/compound-engineering/commands/workflows/compound.md`
121+
- Doc style skills: `plugins/compound-engineering/skills/document-review/`, `plugins/compound-engineering/skills/every-style-editor/`
122+
- Plugin versioning: `docs/solutions/plugin-versioning-requirements.md`

0 commit comments

Comments
 (0)