diff --git a/docs/index.html b/docs/index.html index 08021995..9dcb0f16 100644 --- a/docs/index.html +++ b/docs/index.html @@ -4,7 +4,7 @@ Compounding Engineering - AI-Powered Development Tools for Claude Code - + @@ -161,7 +161,7 @@

Your Code Reviews Just Got 12 Expert Opinions. In 30 Seconds.

- Here's what happened when we shipped yesterday: security audit, performance analysis, architectural review, pattern detection, and eight more specialized checks—all running in parallel. No meetings. No waiting. Just answers. That's compounding engineering: 29 specialized agents, 23 workflow commands, and 18 skills that make today's work easier than yesterday's. + Here's what happened when we shipped yesterday: security audit, performance analysis, architectural review, pattern detection, and eight more specialized checks—all running in parallel. No meetings. No waiting. Just answers. That's compounding engineering: 29 specialized agents, 23 workflow commands, and 19 skills that make today's work easier than yesterday's.

@@ -683,7 +683,7 @@

Utility Commands

- 18 Intelligent Skills + 19 Intelligent Skills

Domain expertise on tap. Need to write a Ruby gem? The andrew-kane-gem-writer knows the patterns Andrew uses in 50+ popular gems. Building a Rails app? The dhh-rails-style enforces 37signals conventions. Generating images? The gemini-imagegen has Google's AI on speed dial. Just invoke the skill and watch it work. @@ -750,6 +750,14 @@

Development Tools

Capture solved problems as categorized documentation with YAML schema.

skill: compound-docs
+
+
+ compound-foundations + Foundations +
+

Audit repo foundations, generate missing docs artifacts, and promote repeated findings.

+ skill: compound-foundations +
@@ -989,7 +997,7 @@

Frequently Asked Questions

Free & Open Source

Install Once. Compound Forever.

- Your next code review takes 30 seconds. The one after that? Even faster. That's compounding. Get 29 expert agents, 23 workflow commands, and 18 specialized skills working for you right now. + Your next code review takes 30 seconds. The one after that? Even faster. That's compounding. Get 29 expert agents, 23 workflow commands, and 19 specialized skills working for you right now.

diff --git a/docs/pages/changelog.html b/docs/pages/changelog.html index dd0c72dc..8b3746a5 100644 --- a/docs/pages/changelog.html +++ b/docs/pages/changelog.html @@ -35,7 +35,7 @@

Reference
@@ -48,6 +48,7 @@

Resources

On This Page

+
+
+

compound-foundations

+ Foundations +
+

+ Your repo solves issues, but the learnings never graduate into conventions or enforcement. This skill closes that loop. It audits foundations, generates missing docs artifacts, promotes repeated findings into conventions, and tracks tech debt with occurrence-based promotion rules. +

+

Core Workflows

+ +

Generated Artifacts

+ +
+ 
skill: compound-foundations
+
+
+

agent-native-architecture

diff --git a/docs/plans/2026-02-13-compound-foundations-shaping.md b/docs/plans/2026-02-13-compound-foundations-shaping.md new file mode 100644 index 00000000..13ec0943 --- /dev/null +++ b/docs/plans/2026-02-13-compound-foundations-shaping.md @@ -0,0 +1,219 @@ +--- +shaping: true +status: active +date: 2026-02-13 +topic: compound-foundations +--- + +# Compound Foundations -- Shaping + +## What We're Building + +Integrate compound foundations into the compound-engineering plugin so that users can strengthen their repo's foundation for agent-first development through existing commands. `/setup` gains a foundations audit that checks for and generates missing artifacts in `docs/`. `/compound` gains a promotion path so findings compound from docs into conventions into enforcement rules. The `compound-foundations` skill is added to the plugin as reference knowledge. + +## Why This Approach (Shape C) + +Three shapes were considered: + +- **A (extend both commands):** Passed most checks but didn't add skill knowledge to the plugin. Dead-end. +- **B (new `/foundations` command):** Clean separation but split the audit away from setup, adding a new command users rarely discover. Friction. +- **C (enhance compound loop + foundations in setup):** Natural integration. Setup audits, compound promotes. Skill provides depth. Passes all requirements. + +Shape C was selected because it reuses existing surfaces (no new commands to learn) and distributes foundations knowledge through the plugin's existing skill/reference system. + +## Requirements (R) + +| ID | Requirement | Status | +|----|-------------|--------| +| R0 | `/setup` audits repo foundations and generates missing artifacts | Core goal | +| R1 | `/compound` has promotion path: finding -> convention -> enforcement | Core goal | +| R2 | Works across languages/frameworks (not Ruby-specific) | Must-have | +| R3 | Convention over configuration -- files always in `docs/`, no config paths | Must-have | +| R4 | Progressive adoption -- users opt into foundations features, not forced | Must-have | +| R5 | Foundations knowledge lives in plugin skill with references/workflows/assets | Must-have | +| R6 | CLAUDE.md quality check is part of the audit | Leaning yes | +| R7 | Quality score tracking per module is offered during setup | Leaning yes | +| R8 | Tech debt file is created with promotion rules baked in | Leaning yes | + +## Convention: docs/ Is the Standard Location + +All generated artifacts live in `docs/`. No configurable paths. The plugin knows where to find things because the convention IS the configuration. + +``` +CLAUDE.md # The map (audited, not generated) +compound-engineering.local.md # Plugin settings (review agents only) + +docs/ +├── ARCHITECTURE.md # Codemap (matklad-style) +├── CONVENTIONS.md # Coding standards + enforcement +├── TECH_DEBT.md # Debt tracker with promotion rules +├── QUALITY_SCORE.md # Per-module quality baseline +├── SECURITY.md # Security patterns (optional) +├── RELIABILITY.md # Reliability / ops (optional) +├── FRONTEND.md # Frontend patterns (optional) +├── DESIGN.md # Design system (optional) +├── PRODUCT_SENSE.md # Product context (optional) +│ +├── solutions/ # ← existing (compound) +├── plans/ # ← existing (plan, with status frontmatter) +├── design-docs/ # Decision records / ADRs +├── product-specs/ # Product specifications (optional) +├── references/ # External docs, llms.txt files (optional) +└── generated/ # Auto-generated docs (optional) +``` + +**Naming convention:** `SCREAMING_CASE.md` for single docs, `lowercase/` for collections. + +### Audit Tiers + +Not every repo needs all of these. The audit checks progressively: + +| Tier | Artifacts | When | +|------|-----------|------| +| **Core** | CLAUDE.md, CONVENTIONS.md, TECH_DEBT.md | Every repo | +| **Recommended** | ARCHITECTURE.md, QUALITY_SCORE.md, design-docs/, plans/ | Most repos | +| **Stack-specific** | FRONTEND.md, DESIGN.md, SECURITY.md, RELIABILITY.md | Detected from project type | +| **Product** | PRODUCT_SENSE.md, product-specs/ | Product repos | +| **Reference** | references/, generated/ | Library-heavy, auto-gen content | + +## Selected Shape: C + +### Parts + +| Part | Mechanism | +|------|-----------| +| **C1** | `/setup` gains "Foundations" section: tiered audit of `docs/`, offer to generate missing artifacts. | +| **C3** | `/compound` gains promotion paths: "Promote to convention" (append to `docs/CONVENTIONS.md`), "Track as tech debt" (add to `docs/TECH_DEBT.md`). Looks in `docs/` directly. | +| **C4** | `/compound` Step 7 enhanced: when 3+ similar findings exist in `docs/solutions/`, auto-suggest "promote to convention." The feedback loop trigger. | +| **C5** | `compound-foundations` skill added to plugin with references/, workflows/, and assets/. Covers all 10 principles. | +| **C6** | Remove empty `docs/patterns/` scaffolding. All pattern knowledge lives in the skill. | + +*C2 (settings integration) was removed. Convention over configuration -- files are always in `docs/`.* + +### Part Details + +#### C5: Compound Foundations Skill (Build First) + +Router-style skill following the `create-agent-skills` pattern. Three directories: knowledge to read, procedures to follow, templates to copy. + +``` +skills/compound-foundations/ +├── SKILL.md # Router: 10 principles + intake + routing table +├── references/ # Knowledge to READ (one per principle) +│ ├── agent-legibility-checklist.md # Actionable checklist for agent-readable repos +│ ├── feedback-loop-patterns.md # Review -> docs -> lint promotion ladder +│ ├── progressive-disclosure.md # CLAUDE.md as map, doc hierarchy +│ ├── mechanical-enforcement.md # Per-language enforcement patterns +│ ├── entropy-management.md # Gardening patterns, quality tracking +│ ├── repo-as-system-of-record.md # What goes in the repo and where +│ ├── plans-as-artifacts.md # Frontmatter, status, decision logs +│ ├── architecture-docs.md # matklad-style ARCHITECTURE.md guidance +│ ├── corrections-over-waiting.md # Throughput > perfect gates +│ └── visibility-and-tooling.md # Dashboards, status bars, structured logs +├── workflows/ # Procedures to FOLLOW +│ ├── audit-foundations.md # Step-by-step foundations audit (used by /setup) +│ ├── promote-to-convention.md # Promotion workflow (used by /compound) +│ ├── track-tech-debt.md # Tech debt tracking workflow +│ └── generate-artifacts.md # Generate missing docs +└── assets/ # Templates to COPY into user repos + ├── CONVENTIONS.md # Language-agnostic starter + ├── TECH_DEBT.md # Debt tracker with promotion rules + ├── QUALITY_SCORE.md # Per-module quality baseline + ├── ARCHITECTURE.md # matklad-style codemap starter + ├── CLAUDE_MD.md # Map-style CLAUDE.md starter (~100 lines) + ├── SECURITY.md # Security patterns starter (optional) + ├── FRONTEND.md # Frontend patterns starter (optional) + └── DESIGN.md # Design system starter (optional) +``` + +The skill is invoked by `/setup` during foundations audit and available standalone. + +#### C1: `/setup` Foundations Audit + +After the existing review agent configuration (Steps 1-5), add: + +**Step 6: Foundations Check (optional)** + +AskUserQuestion: "Would you like to audit your repo's foundations? Checks CLAUDE.md quality, conventions, tech debt tracking, and more." +- "Yes (Recommended)" -- run `workflows/audit-foundations.md` +- "Skip" -- finish setup + +The audit workflow runs through tiers: + +**Core tier (always):** +1. CLAUDE.md -- exists? Under 200 lines? Has pointers to `docs/`? +2. docs/CONVENTIONS.md -- exists? Or language-specific equivalent (.rubocop.yml, .eslintrc, pyproject.toml)? +3. docs/TECH_DEBT.md -- exists? Has promotion rules? + +**Recommended tier (suggest):** +4. docs/ARCHITECTURE.md -- exists? Is it a codemap or a novel? +5. docs/QUALITY_SCORE.md -- exists? Covers modules? +6. docs/design-docs/ -- exists? Has decision records? +7. docs/plans/ -- exists? Plans have status frontmatter? + +**Stack-specific tier (detect project type):** +8. docs/FRONTEND.md -- if project has frontend (package.json, app/javascript/, etc.) +9. docs/SECURITY.md -- if project handles auth, payments, or user data +10. docs/DESIGN.md -- if project has design system (components, tokens, etc.) + +Present findings as a scorecard. Offer to generate missing artifacts using templates from `assets/`. + +#### C3: `/compound` Promotion Paths + +After the existing decision menu (Options 1-7), add: + +**Option 8: Promote to convention** +- Check if `docs/CONVENTIONS.md` exists +- If yes: append finding as a new convention entry +- If no: suggest running `/setup` first +- Format: concise rule + rationale + link back to `docs/solutions/` source +- Invokes `workflows/promote-to-convention.md` + +**Option 9: Track as tech debt** +- Check if `docs/TECH_DEBT.md` exists +- If yes: add/update entry with occurrence count +- If entry already exists: bump occurrence count +- If occurrences >= 3: suggest "promote to convention" (the loop!) +- Invokes `workflows/track-tech-debt.md` + +#### C4: Auto-Promotion Trigger + +In `/compound` Step 7 (cross-reference and pattern detection), after checking for similar issues: + +If 3+ similar findings exist in `docs/solutions/` for the same pattern: +- Auto-suggest: "This pattern has appeared 3+ times. Consider promoting to a convention." +- Surface Option 8 in the decision menu + +This is the mechanical feedback loop trigger. It doesn't auto-promote (user decides) but it surfaces the signal. + +#### C6: Clean Up Empty docs/patterns/ + +The currently empty `docs/patterns/` directory (with empty subdirs hooks/, structures/, transitions/, voice/) is removed. All pattern knowledge lives in the skill's `references/` directory. + +## Key Decisions + +- **Enhance existing commands, don't add new ones:** Maximum adoption, minimum friction. +- **Convention over configuration:** Files always in `docs/`. No configurable paths. No `foundations:` config block needed. +- **Consistent naming:** `SCREAMING_CASE.md` for single docs, `lowercase/` for collections in `docs/`. +- **Language-agnostic templates:** Artifact generation detects language and generates appropriate content. +- **User decides promotion:** Auto-detection surfaces signals (3+ similar findings), but promotion is always user-initiated. +- **Skill as knowledge layer:** The compound-foundations skill provides depth. Commands provide action. +- **Tiered audit:** Core checks always run. Recommended suggested. Stack-specific detected. Nothing forced. +- **Workflows decouple commands from logic:** `/setup` and `/compound` call skill workflows rather than embedding logic inline. + +## Influences + +- **matklad ARCHITECTURE.md:** Keep docs short. Answer "where's the thing that does X?" Codemap, not atlas. +- **OpenAI Codex ExecPlans:** Plans are self-contained. Agents are novices. Anchor on observable behavior. +- **OpenAI Harness Engineering:** 10 principles for agent-first repos. Maps not manuals. Feedback loops. Mechanical enforcement. +- **Plugin patterns:** `agent-native-architecture` (14 refs), `create-agent-skills` (13 refs + 10 workflows + 2 templates). + +## Open Questions + +- Should the CLAUDE.md audit suggest specific improvements or just flag issues? +- Should quality score generation auto-detect test coverage, or just create a manual template? +- How opinionated should generated CONVENTIONS.md be vs. a blank template? + +## Next Steps + +-> `/workflows:plan` for implementation details (C5 skill first, then C1 setup, then C3-C4 compound, then C6 cleanup). diff --git a/docs/plans/2026-02-13-feat-compound-foundations-plan.md b/docs/plans/2026-02-13-feat-compound-foundations-plan.md new file mode 100644 index 00000000..f6051d8e --- /dev/null +++ b/docs/plans/2026-02-13-feat-compound-foundations-plan.md @@ -0,0 +1,359 @@ +--- +title: "feat: Add Compound Foundations Skill and Integrate into Setup + Compound" +type: feat +status: active +date: 2026-02-13 +shaping: docs/plans/2026-02-13-compound-foundations-shaping.md +--- + +# Add Compound Foundations Skill and Integrate into Setup + Compound + +## Overview + +Add a `compound-foundations` skill to the compound-engineering plugin that teaches agent-first repo foundations, then integrate it into `/setup` (foundations audit + artifact generation) and `/compound` (promotion to convention + tech debt tracking). This closes the feedback loop: documented solutions compound into conventions, which compound into enforcement. + +## Problem Statement / Motivation + +Currently, the compound-engineering plugin captures problems (`/compound` -> `docs/solutions/`) and generates plans (`/workflows:plan` -> `docs/plans/`), but there is no path for findings to graduate into conventions or enforcement. Solutions accumulate in `docs/solutions/` and never compound. The plugin also lacks guidance on repo structure for agent-first development -- no audit of CLAUDE.md quality, no convention templates, no tech debt tracking with promotion rules. + +## Proposed Solution + +**Shape C from the shaping doc:** Enhance existing commands, don't add new ones. Add `compound-foundations` skill as the knowledge + workflow + template layer. `/setup` invokes it for auditing. `/compound` invokes it for promotion. + +## Technical Approach + +### Architecture + +Changes touch 3 existing files and add 1 new skill directory (22+ new files): + +| Component | File | Change | +|-----------|------|--------| +| New skill | `skills/compound-foundations/` | New router-style skill (SKILL.md + 10 refs + 4 workflows + 8 assets) | +| Setup | `skills/setup/SKILL.md` | Add Step 6: Foundations Audit | +| Compound docs | `skills/compound-docs/SKILL.md` | Add Options 8-9 to decision gate, enhance Step 7 | +| Compound cmd | `commands/workflows/compound.md` | Sync "What's next?" menu with compound-docs | +| Cleanup | `docs/patterns/` | Remove empty scaffolding | +| Versioning | `plugin.json`, `CHANGELOG.md`, `README.md`, `docs/` pages | Version bump 2.33.1 -> 2.34.0 | + +### Key Design Decisions + +**Q1 - Similarity detection for 3+ threshold:** Same category directory in `docs/solutions/` + 2 or more overlapping tags in YAML frontmatter. Simple, deterministic, no LLM needed. + +**Q2 - Option 2 (Required Reading) vs Option 8 (Convention):** Both kept. Clearly differentiated: +- Option 2 = "Required Reading" -- patterns agents must read before generating code (lives in `docs/solutions/patterns/critical-patterns.md`) +- Option 8 = "Convention" -- coding standards the team follows (lives in `docs/CONVENTIONS.md`) + +**Q3 - Step 7 vs C4:** C4 enhances Step 7, doesn't replace it. Step 7 still writes to `common-solutions.md`. C4 adds a promotion suggestion when the 3+ threshold is met. + +**Q4 - TECH_DEBT.md format:** Markdown table with columns: Issue | Occurrences | Severity | Status | Source. Machine-parseable. Template defines exact format. + +**Q5 - Missing file fallback:** When Option 8/9 is selected but target file doesn't exist, create it in-place from the asset template rather than redirecting to `/setup`. Keep user in flow. + +**Q6 - Generate semantics:** Templates are starters with `[PLACEHOLDER]` markers. Agent reads template + project context and generates a populated version. Some sections are generic (keep as-is), some are project-specific (fill in). + +**Q7 - CLAUDE.md:** Offer to generate from template only when no CLAUDE.md exists at all. For existing CLAUDE.md, audit quality only. + +**Q8 - Scorecard format:** Markdown table: `| Artifact | Status | Action |` with summary line `"5/8 foundations present."` + +**Q9 - Options 8-9 visibility:** Always show in decision menu. Add `(suggested)` tag when Step 7 detected a pattern. + +### Implementation Phases + +#### Phase 1: Compound Foundations Skill (C5) + +Build the skill first -- setup and compound depend on its workflows and assets. + +**1.1 Create SKILL.md (Router Pattern)** + +File: `skills/compound-foundations/SKILL.md` + +Structure following `agent-native-architecture` pattern: +- `` -- The 10 compound foundations principles (condensed) +- `` -- "What aspect of repo foundations do you need help with?" + 1. Audit my repo's foundations + 2. Learn about a specific principle + 3. Generate a missing artifact + 4. Promote a finding to convention + 5. Track tech debt +- `` -- Maps intake to workflows or references +- `` -- Lists all 10 reference files +- `` -- Lists all 4 workflows +- `` -- Checklist + +Source material: `~/.claude/skills/harness-engineering/SKILL.md` (personal skill, 10 principles). Rebrand all "harness" language to "compound foundations." + +**1.2 Create Reference Files (10 files)** + +Directory: `skills/compound-foundations/references/` + +| File | Source | Content | +|------|--------|---------| +| `agent-legibility-checklist.md` | New (referenced but never existed in personal skill) | Actionable checklist: boring tech, reimpl small utils, error messages that teach, greppable code | +| `feedback-loop-patterns.md` | Principle 8 | The promotion ladder: review comment -> doc -> convention -> lint rule. Examples per language. | +| `progressive-disclosure.md` | Principle 4 | CLAUDE.md as map (~100 lines). Doc hierarchy. 2-hop navigation. | +| `mechanical-enforcement.md` | Principle 5 | Per-language: Rakefile, package.json scripts, Makefile, pyproject.toml. Structural tests. Custom linters. | +| `entropy-management.md` | Principle 9 | Gardening patterns. Quality tracking. Background cleanup. Drift detection. | +| `repo-as-system-of-record.md` | Principle 2 | Push knowledge into repo. Design decisions, product specs, references, architecture. | +| `plans-as-artifacts.md` | Principle 3 | Frontmatter with status. Decision logs. Progress tracking. Codex ExecPlan influence. | +| `architecture-docs.md` | matklad influence | Codemap not atlas. Name files/modules/types. Invariants (esp. absence). Cross-cutting concerns. | +| `corrections-over-waiting.md` | Principle 7 | High throughput > perfect gates. Short-lived PRs. Follow-up fixes. Reserve gates for irreversible. | +| `visibility-and-tooling.md` | Principle 10 | Dashboard, status bar, structured logs, per-worktree isolation. | + +Each file: 100-200 lines. Follows pattern from `agent-native-architecture/references/` -- overview, core principle, patterns, anti-patterns, examples. + +**1.3 Create Workflow Files (4 files)** + +Directory: `skills/compound-foundations/workflows/` + +Each workflow has ``, ``, `` (per `create-agent-skills/workflows/` convention). + +| File | Used by | Steps | +|------|---------|-------| +| `audit-foundations.md` | `/setup` Step 6 | Read refs: progressive-disclosure, repo-as-system-of-record. Run tiered checks (core -> recommended -> stack-specific). Present scorecard. Offer generation per missing artifact. | +| `promote-to-convention.md` | `/compound` Option 8 | Read refs: feedback-loop-patterns. Check if `docs/CONVENTIONS.md` exists (create from template if not). Check for duplicate convention. Append entry: rule + rationale + source link. | +| `track-tech-debt.md` | `/compound` Option 9 | Read refs: entropy-management. Check if `docs/TECH_DEBT.md` exists (create from template if not). Parse table for existing entry. Add new or bump occurrence count. If count >= 3, suggest promotion. | +| `generate-artifacts.md` | `/setup` Step 6 | Read refs: progressive-disclosure, mechanical-enforcement. For each missing artifact: read corresponding asset template, read project context (language, structure), generate populated version, write to `docs/`. | + +**1.4 Create Asset Templates (8 files)** + +Directory: `skills/compound-foundations/assets/` + +| File | Target | Content | +|------|--------|---------| +| `CONVENTIONS.md` | `docs/CONVENTIONS.md` | Section headers: Code Style, Naming, Error Handling, Testing, Infrastructure Patterns. 2-3 example entries per section marked as `[EXAMPLE - replace with your conventions]`. | +| `TECH_DEBT.md` | `docs/TECH_DEBT.md` | Header explaining promotion rules (3+ occurrences -> promote). Table: `\| Issue \| Occurrences \| Severity \| Status \| Source \|`. One example entry. | +| `QUALITY_SCORE.md` | `docs/QUALITY_SCORE.md` | Header. Table: `\| Module \| Tests \| Last Reviewed \| Grade \| Known Issues \|`. Instructions for grades (A-D). | +| `ARCHITECTURE.md` | `docs/ARCHITECTURE.md` | matklad-style: Bird's eye overview, Codemap (module -> purpose), Data flow, Invariants, Cross-cutting concerns. All sections have `[PLACEHOLDER]` markers. | +| `CLAUDE_MD.md` | `CLAUDE.md` | Map-style ~100 lines. Sections: What Is This, Directory Structure, Key Concepts, Pointers (to docs/CONVENTIONS, docs/ARCHITECTURE, etc.), Commands, Tone. | +| `SECURITY.md` | `docs/SECURITY.md` | Auth patterns, input validation boundaries, secrets management, dependency auditing. | +| `FRONTEND.md` | `docs/FRONTEND.md` | Component conventions, state management, API integration patterns, accessibility. | +| `DESIGN.md` | `docs/DESIGN.md` | Design tokens, component library, layout patterns, responsive strategy. | + +Note: RELIABILITY.md and PRODUCT_SENSE.md are out of scope for this iteration. Remove from the directory structure documentation. Can be added later. + +#### Phase 2: Setup Enhancement (C1) + +**2.1 Add Step 6 to `skills/setup/SKILL.md`** + +After existing Step 5 (Confirm), append: + +```markdown +## Step 6: Foundations Check (optional) + +Use AskUserQuestion: + +question: "Would you like to audit your repo's foundations? Checks CLAUDE.md quality, conventions, tech debt tracking, and more." +header: "Foundations" +options: + - label: "Yes (Recommended)" + description: "Run tiered audit: CLAUDE.md quality, conventions, tech debt, architecture docs." + - label: "Skip" + description: "Finish setup without auditing foundations." + +If "Skip": end setup. +If "Yes": invoke `compound-foundations` skill workflow `workflows/audit-foundations.md`. +``` + +The workflow handles everything: tiered checks, scorecard presentation, artifact generation offers. Setup just invokes it. + +#### Phase 3: Compound Enhancement (C3 + C4) + +**3.1 Add Options 8-9 to `skills/compound-docs/SKILL.md`** + +In the `` block (around line 279), after existing Option 7, add: + +```markdown +8. Promote to convention - Graduate this finding to docs/CONVENTIONS.md +9. Track as tech debt - Add to docs/TECH_DEBT.md with occurrence tracking +``` + +For Option 8: invoke `workflows/promote-to-convention.md` from `compound-foundations` skill. +For Option 9: invoke `workflows/track-tech-debt.md` from `compound-foundations` skill. + +Both workflows handle the "file doesn't exist" case by creating from template in-place. + +Add differentiation text between Option 2 and Option 8: +- Option 2: "Required Reading -- patterns agents must know before generating code" +- Option 8: "Convention -- coding standards your team follows" + +**3.2 Enhance Step 7 with auto-promotion trigger (C4)** + +In `skills/compound-docs/SKILL.md` Step 7 (cross-reference and pattern detection, around line 201), after the existing 3+ similar issues check that writes to `common-solutions.md`, add: + +```markdown +**Promotion suggestion:** If 3+ similar findings exist (same category directory + 2+ overlapping tags), add to the decision menu: +"This pattern has appeared [N] times. Consider promoting to a convention (Option 8)." +Tag Option 8 with "(suggested)" in the decision menu. +``` + +This supplements the existing Step 7 behavior, doesn't replace it. + +**3.3 Sync `commands/workflows/compound.md` menu** + +The compound.md file (lines 173-181) has a simpler 5-option "What's next?" menu that's out of sync with compound-docs' 7-option menu. Update it to match the new 9-option menu from compound-docs, or remove the duplicate menu and defer entirely to the skill's decision gate. + +Recommendation: Remove the compound.md menu duplication. The skill's `` is authoritative. compound.md should say "Proceed to the decision gate in the compound-docs skill" rather than maintaining its own list. + +#### Phase 4: Cleanup + Versioning (C6) + +**4.1 Remove empty `docs/patterns/`** + +Delete: +- `docs/patterns/hooks/` +- `docs/patterns/structures/` +- `docs/patterns/transitions/` +- `docs/patterns/voice/` +- `docs/patterns/` + +Confirm that `docs/solutions/patterns/` (used by compound-docs Step 7) is NOT affected -- it's a different path. + +**4.2 Version bump** + +- `.claude-plugin/plugin.json`: `2.33.1` -> `2.34.0` (new skill = minor). Update description: "20 skills" (was 19). +- `CHANGELOG.md`: Add `## [2.34.0] - 2026-02-13` entry. +- `README.md`: Update skill count table, add compound-foundations to skill list. +- `docs/` pages: Update sidebar counts, add entries where needed. + +## Alternative Approaches Considered + +See shaping doc (`docs/plans/2026-02-13-compound-foundations-shaping.md`) for full evaluation of 3 shapes. Shape C (enhance existing commands) was selected over Shape A (extend both, no skill) and Shape B (new `/foundations` command). + +Within Shape C, we considered a `foundations:` config block in `compound-engineering.local.md` with configurable paths. Removed in favor of convention over configuration -- files always in `docs/`. + +## Acceptance Criteria + +### Functional Requirements + +- [x] `skills/compound-foundations/SKILL.md` exists as router-style skill +- [x] 10 reference files cover all 10 principles +- [x] 4 workflow files (audit, promote, track-debt, generate) +- [x] 8 asset templates for artifact generation +- [x] `/setup` offers Step 6 foundations audit after existing config +- [x] Audit checks core tier (CLAUDE.md, CONVENTIONS.md, TECH_DEBT.md) +- [x] Audit checks recommended tier (ARCHITECTURE.md, QUALITY_SCORE.md, design-docs/, plans/) +- [x] Audit checks stack-specific tier based on project detection +- [x] Scorecard presented as markdown table with status + action columns +- [x] Missing artifacts can be generated from templates +- [x] `/compound` decision menu has Options 8 (convention) and 9 (tech debt) +- [x] Option 8 appends to `docs/CONVENTIONS.md` (creates from template if missing) +- [x] Option 9 adds/updates entry in `docs/TECH_DEBT.md` with occurrence count +- [x] Occurrence count >= 3 triggers promotion suggestion +- [x] Step 7 auto-suggests promotion when 3+ similar findings detected +- [x] Option 2 (Required Reading) and Option 8 (Convention) clearly differentiated +- [x] Empty `docs/patterns/` removed +- [x] `docs/solutions/patterns/` NOT affected + +### Non-Functional Requirements + +- [x] Templates are language-agnostic (work for Ruby, Python, TypeScript, Go, etc.) +- [x] All reference files are 100-200 lines +- [x] SKILL.md follows router pattern (XML tags, intake, routing table) +- [x] Workflows follow convention (required_reading, process, success_criteria) +- [x] No new commands -- only enhances existing `/setup` and `/compound` + +### Quality Gates + +- [x] Version bumped to 2.34.0 +- [x] CHANGELOG.md entry added +- [x] README.md skill count updated (19 -> 20) +- [x] README.md skill table includes compound-foundations +- [x] plugin.json description updated +- [x] docs/ pages updated with new counts + +## Dependencies & Prerequisites + +- Shaping doc: `docs/plans/2026-02-13-compound-foundations-shaping.md` (approved) +- Source material: `~/.claude/skills/harness-engineering/SKILL.md` (personal skill, 10 principles) +- Existing patterns: `skills/agent-native-architecture/` (14 refs, router), `skills/create-agent-skills/` (13 refs, 10 workflows, 2 templates) + +## Risk Analysis & Mitigation + +| Risk | Impact | Mitigation | +|------|--------|------------| +| Options 8-9 add decision fatigue (9 options total) | Users overwhelmed | Always show, but mark "(suggested)" only when pattern detected. Clear differentiation text. | +| TECH_DEBT.md format fragile to manual edits | Occurrence bumping breaks | Define rigid table format in template. Parse defensively. | +| Concurrent edits in multi-agent setup | File corruption | Workflows should note atomic write patterns where relevant. | +| Templates too generic to be useful | Users delete and start over | Fill in project-specific sections during generation. Mark examples clearly. | +| Step 7 + C4 double-trigger confusion | User prompted twice | C4 supplements Step 7 with a suggestion, not a separate prompt. One decision menu, not two. | + +## File Manifest + +### New Files (22) + +``` +skills/compound-foundations/ +├── SKILL.md +├── references/ +│ ├── agent-legibility-checklist.md +│ ├── feedback-loop-patterns.md +│ ├── progressive-disclosure.md +│ ├── mechanical-enforcement.md +│ ├── entropy-management.md +│ ├── repo-as-system-of-record.md +│ ├── plans-as-artifacts.md +│ ├── architecture-docs.md +│ ├── corrections-over-waiting.md +│ └── visibility-and-tooling.md +├── workflows/ +│ ├── audit-foundations.md +│ ├── promote-to-convention.md +│ ├── track-tech-debt.md +│ └── generate-artifacts.md +└── assets/ + ├── CONVENTIONS.md + ├── TECH_DEBT.md + ├── QUALITY_SCORE.md + ├── ARCHITECTURE.md + ├── CLAUDE_MD.md + ├── SECURITY.md + ├── FRONTEND.md + └── DESIGN.md +``` + +### Modified Files (4) + +``` +skills/setup/SKILL.md # Add Step 6 +skills/compound-docs/SKILL.md # Add Options 8-9, enhance Step 7 +commands/workflows/compound.md # Sync menu or remove duplicate +``` + +### Deleted (4 empty dirs) + +``` +docs/patterns/hooks/ +docs/patterns/structures/ +docs/patterns/transitions/ +docs/patterns/voice/ +``` + +### Versioning Files (3+) + +``` +.claude-plugin/plugin.json # 2.33.1 -> 2.34.0 +CHANGELOG.md # New entry +README.md # Skill count + table +docs/index.html # Stats +docs/pages/skills.html # New skill entry +docs/pages/changelog.html # New version +``` + +## References & Research + +### Internal References +- Shaping doc: `docs/plans/2026-02-13-compound-foundations-shaping.md` +- Router pattern exemplar: `skills/agent-native-architecture/SKILL.md` +- Workflow pattern exemplar: `skills/create-agent-skills/workflows/create-new-skill.md` +- Asset pattern exemplar: `skills/compound-docs/assets/resolution-template.md` +- Decision gate location: `skills/compound-docs/SKILL.md:260-343` +- Setup skill: `skills/setup/SKILL.md` (169 lines, 5 steps) +- Compound command: `commands/workflows/compound.md` (duplicate menu at lines 173-181) + +### External References +- matklad ARCHITECTURE.md: https://matklad.github.io/2021/02/06/ARCHITECTURE.md.html +- OpenAI Codex ExecPlans: https://developers.openai.com/cookbook/articles/codex_exec_plans +- OpenAI Harness Engineering: https://openai.com/index/harness-engineering/ + +### Source Material +- Personal harness-engineering skill: `~/.claude/skills/harness-engineering/SKILL.md` +- Erf repo foundations (test case): `~/erf/docs/CONVENTIONS.md`, `~/erf/docs/tech-debt.md`, `~/erf/docs/QUALITY_SCORE.md` diff --git a/plugins/compound-engineering/.claude-plugin/plugin.json b/plugins/compound-engineering/.claude-plugin/plugin.json index cb392919..77ec1f88 100644 --- a/plugins/compound-engineering/.claude-plugin/plugin.json +++ b/plugins/compound-engineering/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "compound-engineering", - "version": "2.33.1", - "description": "AI-powered development tools. 29 agents, 22 commands, 19 skills, 1 MCP server for code review, research, design, and workflow automation.", + "version": "2.34.1", + "description": "AI-powered development tools. 29 agents, 22 commands, 20 skills, 1 MCP server for code review, research, design, and workflow automation.", "author": { "name": "Kieran Klaassen", "email": "kieran@every.to", diff --git a/plugins/compound-engineering/CHANGELOG.md b/plugins/compound-engineering/CHANGELOG.md index 4669c01e..789adbe2 100644 --- a/plugins/compound-engineering/CHANGELOG.md +++ b/plugins/compound-engineering/CHANGELOG.md @@ -5,6 +5,35 @@ All notable changes to the compound-engineering plugin will be documented in thi The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [2.34.1] - 2026-02-13 + +### Fixed + +- **`/workflows:work` Phase 4 Step 4** — Strengthened "Update Plan Status" to require updating the original plan document with completion summary, `completed_by`, `completed_date`, and `actual_effort` frontmatter fields. Explicitly prohibits creating separate completion report files (e.g. `COMPLETION_REPORT.md`). The plan is the single source of truth for both planning and delivery. +- **`/workflows:work` pitfalls** — Added anti-pattern: "Creating separate completion reports — update the plan file itself." + +--- + +## [2.34.0] - 2026-02-13 + +### Added + +- **`compound-foundations` skill** - New foundations skill with router-style `SKILL.md`, 10 principle references, 4 workflows, and 8 artifact templates. +- **`setup` skill Step 6** - Optional foundations audit now runs after setup confirmation and invokes `compound-foundations/workflows/audit-foundations.md`. +- **`compound-docs` decision gate Options 8 and 9** - Added promotion to `docs/CONVENTIONS.md` and tracking in `docs/TECH_DEBT.md`. + +### Changed + +- **`compound-docs` Step 7** - Added promotion suggestion when 3+ similar findings are detected (same category + overlapping tags), with Option 8 marked as suggested. +- **`/workflows:compound` command** - Removed duplicate post-capture menu and now defers to the `compound-docs` decision gate as source of truth. +- **Plugin metadata and docs** - Version bumped to `2.34.0`; skill count updated for the new foundations skill. + +### Removed + +- **Empty docs scaffolding** - Removed `docs/patterns/` empty directory structure from the compound-engineering plugin. + +--- + ## [2.33.1] - 2026-02-13 ### Changed diff --git a/plugins/compound-engineering/README.md b/plugins/compound-engineering/README.md index ec1ad83b..ee1bab5b 100644 --- a/plugins/compound-engineering/README.md +++ b/plugins/compound-engineering/README.md @@ -8,7 +8,7 @@ AI-powered development tools that get smarter with every use. Make each unit of |-----------|-------| | Agents | 29 | | Commands | 22 | -| Skills | 19 | +| Skills | 20 | | MCP Servers | 1 | ## Agents @@ -112,6 +112,7 @@ Core workflow commands use `workflows:` prefix to avoid collisions with built-in | Skill | Description | |-------|-------------| | `agent-native-architecture` | Build AI agents using prompt-native architecture | +| `compound-foundations` | Audit repo foundations, generate artifacts, and promote recurring findings | ### Development Tools diff --git a/plugins/compound-engineering/commands/workflows/compound.md b/plugins/compound-engineering/commands/workflows/compound.md index 9dffc1a4..eaaf4018 100644 --- a/plugins/compound-engineering/commands/workflows/compound.md +++ b/plugins/compound-engineering/commands/workflows/compound.md @@ -172,12 +172,10 @@ File created: This documentation will be searchable for future reference when similar issues occur in the Email Processing or Brief System modules. -What's next? -1. Continue workflow (recommended) -2. Link related documentation -3. Update other references -4. View documentation -5. Other +Next step: +Proceed to the `compound-docs` decision gate, which is the authoritative +post-capture menu for continuation, required reading promotion, convention +promotion, and tech debt tracking. ``` ## The Compounding Philosophy diff --git a/plugins/compound-engineering/commands/workflows/work.md b/plugins/compound-engineering/commands/workflows/work.md index c8b7f2c2..e2b754e0 100644 --- a/plugins/compound-engineering/commands/workflows/work.md +++ b/plugins/compound-engineering/commands/workflows/work.md @@ -297,13 +297,49 @@ This command takes a work document (plan, specification, or todo file) and execu )" ``` -4. **Update Plan Status** +4. **Update the Plan Document** (REQUIRED) - If the input document has YAML frontmatter with a `status` field, update it to `completed`: + When work is complete, **update the original plan file** — never create a separate completion report, summary document, or status file. The plan is the living record of what was planned AND what was delivered. + + **Step A: Update frontmatter** + ```yaml + status: completed # was: active + completed_date: YYYY-MM-DD # today's date + completed_by: "Claude Haiku 4.5" # model that did the work + actual_effort: "Description of actual effort" # e.g. "Completed in one session" ``` - status: active → status: completed + + **Step B: Add a completion summary section** at the end of the plan (before any "Out of Scope" or "Future" sections): + ```markdown + ## Completion Summary + + ### What Was Delivered + - [List each major feature/phase completed with checkmarks] + + ### Implementation Statistics + - Files changed, lines added, commits made + - Dependencies added (if any) + - Build/test status + + ### Performance / Results + - Key metrics achieved vs targets + - Test verification results + + ### Git Commits + - [List commit SHAs and messages] + + ### Completion Details + - **Completed By:** [Model name, e.g. Claude Haiku 4.5] + - **Date:** [Date] + - **Session:** [Single session / multiple sessions / etc.] ``` + **Anti-patterns — do NOT do these:** + - Do NOT create a separate `*_COMPLETION_REPORT.md` or `*_SUMMARY.md` file + - Do NOT create files with ALL_CAPS names for completion status + - Do NOT duplicate plan content into a new document + - The plan file itself is the single source of truth for both planning and completion + 5. **Notify User** - Summarize what was completed - Link to PR @@ -452,3 +488,4 @@ For most features: tests + linting + following patterns is sufficient. - **Forgetting TodoWrite** - Track progress or lose track of what's done - **80% done syndrome** - Finish the feature, don't move on early - **Over-reviewing simple changes** - Save reviewer agents for complex work +- **Creating separate completion reports** - Update the plan file itself, never create new files like `COMPLETION_REPORT.md` diff --git a/plugins/compound-engineering/skills/compound-docs/SKILL.md b/plugins/compound-engineering/skills/compound-docs/SKILL.md index 6c8b1bff..c6a87daa 100644 --- a/plugins/compound-engineering/skills/compound-docs/SKILL.md +++ b/plugins/compound-engineering/skills/compound-docs/SKILL.md @@ -234,6 +234,14 @@ cat >> docs/solutions/patterns/common-solutions.md << 'EOF' EOF ``` +**Promotion suggestion:** If 3+ similar findings exist in the same category directory and they share 2+ overlapping tags, add this note to the decision menu: + +``` +This pattern has appeared [N] times. Consider promoting to a convention (Option 8). +``` + +When this condition is met, show Option 8 as `Promote to convention (suggested)`. + **Critical Pattern Detection (Optional Proactive Suggestion):** If this issue has automatic indicators suggesting it might be critical: @@ -271,12 +279,14 @@ File created: What's next? 1. Continue workflow (recommended) -2. Add to Required Reading - Promote to critical patterns (critical-patterns.md) +2. Add to Required Reading - Patterns agents must read before code generation (critical-patterns.md) 3. Link related issues - Connect to similar problems 4. Add to existing skill - Add to a learning skill (e.g., hotwire-native) 5. Create new skill - Extract into new learning skill 6. View documentation - See what was captured 7. Other +8. Promote to convention - Graduate this finding to docs/CONVENTIONS.md +9. Track as tech debt - Add to docs/TECH_DEBT.md with occurrence tracking ``` **Handle responses:** @@ -300,6 +310,8 @@ Action: 4. Add cross-reference back to this doc 5. Confirm: "✓ Added to Required Reading. All subagents will see this pattern before code generation." +Option 2 is for Required Reading patterns agents must know before generating code. + **Option 3: Link related issues** - Prompt: "Which doc to link? (provide filename or describe)" @@ -340,6 +352,25 @@ Action: - Ask what they'd like to do +**Option 8: Promote to convention** + +Action: +1. Invoke `compound-foundations` workflow `workflows/promote-to-convention.md` +2. If `docs/CONVENTIONS.md` does not exist, create it from `compound-foundations/assets/CONVENTIONS.md` in-place +3. Append convention entry with rule + rationale + source link to this solution doc +4. Confirm: "✓ Promoted to convention in docs/CONVENTIONS.md" + +Option 8 is for coding standards your team follows. + +**Option 9: Track as tech debt** + +Action: +1. Invoke `compound-foundations` workflow `workflows/track-tech-debt.md` +2. If `docs/TECH_DEBT.md` does not exist, create it from `compound-foundations/assets/TECH_DEBT.md` in-place +3. Add or update table row with issue, occurrence count, severity, status, source +4. If count reaches 3+, suggest Option 8 promotion +5. Confirm: "✓ Tracked in docs/TECH_DEBT.md" + --- diff --git a/plugins/compound-engineering/skills/compound-foundations/SKILL.md b/plugins/compound-engineering/skills/compound-foundations/SKILL.md new file mode 100644 index 00000000..8fc95c95 --- /dev/null +++ b/plugins/compound-engineering/skills/compound-foundations/SKILL.md @@ -0,0 +1,103 @@ +--- +name: compound-foundations +description: Build agent-first repository foundations. Use this skill to audit foundation quality, generate missing artifacts, promote repeated findings into conventions, and track technical debt with promotion rules. +disable-model-invocation: true +--- + +# Compound Foundations + +Compound foundations turns repo hygiene into a compounding loop: + +`finding -> solution doc -> convention -> enforcement -> less drift` + +Use this skill when you need to improve the repo itself, not just ship one feature. + + +## Essential Principles + +1. **Maps, not manuals**: Keep `CLAUDE.md` short and navigable. +2. **Repo as record**: Put operational knowledge in versioned docs. +3. **Plans as artifacts**: Track execution status in files, not memory. +4. **Progressive disclosure**: Start broad, then go deeper by reference. +5. **Mechanical enforcement**: Move recurring guidance into checks. +6. **Agent legibility**: Optimize for searchability and clear boundaries. +7. **Corrections over waiting**: Prefer short loops and fast corrections. +8. **Promotion loop**: Promote repeated findings into conventions. +9. **Entropy management**: Garden docs and debt continuously. +10. **Visibility and tooling**: Instrument quality so drift is observable. + + + +## What aspect of repo foundations do you need help with? + +1. Audit my repo's foundations +2. Learn about a specific principle +3. Generate a missing artifact +4. Promote a finding to convention +5. Track tech debt + +Wait for the user's response before continuing. + + + +## Routing + +| User Response | Action | +|---|---| +| `1`, `audit`, `foundations` | Run `workflows/audit-foundations.md` | +| `2`, `learn`, `principle` | Show `reference_index` and open requested reference | +| `3`, `generate`, `artifact` | Run `workflows/generate-artifacts.md` | +| `4`, `promote`, `convention` | Run `workflows/promote-to-convention.md` | +| `5`, `tech debt`, `debt` | Run `workflows/track-tech-debt.md` | + +If intent is ambiguous, ask one clarifying question and continue. + + + +## Reference Files + +- `references/agent-legibility-checklist.md` +- `references/feedback-loop-patterns.md` +- `references/progressive-disclosure.md` +- `references/mechanical-enforcement.md` +- `references/entropy-management.md` +- `references/repo-as-system-of-record.md` +- `references/plans-as-artifacts.md` +- `references/architecture-docs.md` +- `references/corrections-over-waiting.md` +- `references/visibility-and-tooling.md` + + + +## Workflow Files + +- `workflows/audit-foundations.md` +- `workflows/promote-to-convention.md` +- `workflows/track-tech-debt.md` +- `workflows/generate-artifacts.md` + + + +## Asset Templates + +- `assets/CONVENTIONS.md` +- `assets/TECH_DEBT.md` +- `assets/QUALITY_SCORE.md` +- `assets/ARCHITECTURE.md` +- `assets/CLAUDE_MD.md` +- `assets/SECURITY.md` +- `assets/FRONTEND.md` +- `assets/DESIGN.md` + + + +## Success Criteria + +- [ ] Core foundations are audited (`CLAUDE.md`, `docs/CONVENTIONS.md`, `docs/TECH_DEBT.md`) +- [ ] Missing artifacts are created from templates when requested +- [ ] Promotion suggestions appear when patterns recur (3+) +- [ ] Conventions include rationale and source links +- [ ] Tech debt entries track occurrence counts and status +- [ ] Outputs are language-agnostic and repo-specific +- [ ] User exits with clear next action and updated docs + diff --git a/plugins/compound-engineering/skills/compound-foundations/assets/ARCHITECTURE.md b/plugins/compound-engineering/skills/compound-foundations/assets/ARCHITECTURE.md new file mode 100644 index 00000000..e3965272 --- /dev/null +++ b/plugins/compound-engineering/skills/compound-foundations/assets/ARCHITECTURE.md @@ -0,0 +1,39 @@ +# ARCHITECTURE + +## Bird's Eye Overview + +[PLACEHOLDER: one-paragraph system summary] + +## Codemap + +- `[PLACEHOLDER module/path]`: [PLACEHOLDER purpose] +- `[PLACEHOLDER module/path]`: [PLACEHOLDER purpose] +- `[PLACEHOLDER module/path]`: [PLACEHOLDER purpose] + +## Data Flow + +1. [PLACEHOLDER: entrypoint] +2. [PLACEHOLDER: validation/parsing] +3. [PLACEHOLDER: domain logic] +4. [PLACEHOLDER: persistence/output] + +## Invariants + +- Must always: [PLACEHOLDER invariant] +- Must always: [PLACEHOLDER invariant] +- Must never: [PLACEHOLDER invariant] +- Must never: [PLACEHOLDER invariant] + +## Cross-Cutting Concerns + +### Observability + +[PLACEHOLDER logging/metrics approach] + +### Security Boundaries + +[PLACEHOLDER auth/input validation boundaries] + +### Performance + +[PLACEHOLDER caching/query/batching guidance] diff --git a/plugins/compound-engineering/skills/compound-foundations/assets/CLAUDE_MD.md b/plugins/compound-engineering/skills/compound-foundations/assets/CLAUDE_MD.md new file mode 100644 index 00000000..f9b7ccec --- /dev/null +++ b/plugins/compound-engineering/skills/compound-foundations/assets/CLAUDE_MD.md @@ -0,0 +1,66 @@ +# CLAUDE.md + +## What Is This + +[PLACEHOLDER: one-paragraph project summary] + +## Directory Structure + +- `app/` or `src/`: [PLACEHOLDER core application code] +- `lib/`: [PLACEHOLDER shared utilities] +- `docs/`: project reference material +- `plans/`: active and completed work plans +- `tests/` or `spec/`: automated tests + +## Key Concepts + +- [PLACEHOLDER concept 1] +- [PLACEHOLDER concept 2] +- [PLACEHOLDER concept 3] + +## Core Docs + +- Conventions: `docs/CONVENTIONS.md` +- Architecture: `docs/ARCHITECTURE.md` +- Tech debt: `docs/TECH_DEBT.md` +- Quality score: `docs/QUALITY_SCORE.md` +- Design docs: `docs/design-docs/` +- Solution archive: `docs/solutions/` + +## Plans + +- Active work: `plans/` +- Plan status fields should use `status: active|completed` + +## Commands + +- Test: `[PLACEHOLDER test command]` +- Lint: `[PLACEHOLDER lint command]` +- Build: `[PLACEHOLDER build command]` + +## Coding Conventions + +Read and follow `docs/CONVENTIONS.md` before implementing new patterns. + +## Architecture Rules + +Read `docs/ARCHITECTURE.md` before changing module boundaries. + +## When You Fix a Non-Trivial Issue + +1. Document in `docs/solutions/[category]/...` +2. If repeated, track in `docs/TECH_DEBT.md` +3. If repeated 3+ times, promote to `docs/CONVENTIONS.md` + +## Review Expectations + +- Keep changes scoped to the requested task. +- Follow existing naming patterns. +- Avoid unrelated refactors. +- Add targeted tests for behavioral changes. + +## Tone + +- Be direct. +- Prefer concrete actions over abstract commentary. +- Include file references when explaining changes. diff --git a/plugins/compound-engineering/skills/compound-foundations/assets/CONVENTIONS.md b/plugins/compound-engineering/skills/compound-foundations/assets/CONVENTIONS.md new file mode 100644 index 00000000..73a0e431 --- /dev/null +++ b/plugins/compound-engineering/skills/compound-foundations/assets/CONVENTIONS.md @@ -0,0 +1,62 @@ +# CONVENTIONS + +This file defines coding conventions that the team follows. +Keep entries concise and enforceable. + +## How to Add a Convention + +Use this format: + +- Rule: [single clear rule] +- Rationale: [why this rule exists] +- Source: [link to issue/solution doc] + +## Code Style + +- Rule: [EXAMPLE - replace with your convention] +- Rationale: [EXAMPLE] +- Source: [EXAMPLE] + +- Rule: [EXAMPLE - replace with your convention] +- Rationale: [EXAMPLE] +- Source: [EXAMPLE] + +## Naming + +- Rule: [EXAMPLE - replace with your convention] +- Rationale: [EXAMPLE] +- Source: [EXAMPLE] + +- Rule: [EXAMPLE - replace with your convention] +- Rationale: [EXAMPLE] +- Source: [EXAMPLE] + +## Error Handling + +- Rule: [EXAMPLE - replace with your convention] +- Rationale: [EXAMPLE] +- Source: [EXAMPLE] + +- Rule: [EXAMPLE - replace with your convention] +- Rationale: [EXAMPLE] +- Source: [EXAMPLE] + +## Testing + +- Rule: [EXAMPLE - replace with your convention] +- Rationale: [EXAMPLE] +- Source: [EXAMPLE] + +- Rule: [EXAMPLE - replace with your convention] +- Rationale: [EXAMPLE] +- Source: [EXAMPLE] + +## Infrastructure Patterns + +- Rule: [EXAMPLE - replace with your convention] +- Rationale: [EXAMPLE] +- Source: [EXAMPLE] + +- Rule: [EXAMPLE - replace with your convention] +- Rationale: [EXAMPLE] +- Source: [EXAMPLE] diff --git a/plugins/compound-engineering/skills/compound-foundations/assets/DESIGN.md b/plugins/compound-engineering/skills/compound-foundations/assets/DESIGN.md new file mode 100644 index 00000000..02b4be37 --- /dev/null +++ b/plugins/compound-engineering/skills/compound-foundations/assets/DESIGN.md @@ -0,0 +1,36 @@ +# DESIGN + +## Design Tokens + +- Color tokens source: [PLACEHOLDER] +- Typography tokens source: [PLACEHOLDER] +- Spacing scale: [PLACEHOLDER] + +## Component Library + +- Primary component source: [PLACEHOLDER] +- Variant naming pattern: [PLACEHOLDER] +- Accessibility requirements: [PLACEHOLDER] + +## Layout Patterns + +- Page shell pattern: [PLACEHOLDER] +- Grid system: [PLACEHOLDER] +- Density/spacing rules: [PLACEHOLDER] + +## Responsive Strategy + +- Breakpoint system: [PLACEHOLDER] +- Mobile-first or desktop-first: [PLACEHOLDER] +- Critical mobile constraints: [PLACEHOLDER] + +## Motion Guidelines + +- Standard durations: [PLACEHOLDER] +- Easing defaults: [PLACEHOLDER] +- Reduced motion handling: [PLACEHOLDER] + +## Design QA + +- Visual regression process: [PLACEHOLDER] +- Review checklist location: [PLACEHOLDER] diff --git a/plugins/compound-engineering/skills/compound-foundations/assets/FRONTEND.md b/plugins/compound-engineering/skills/compound-foundations/assets/FRONTEND.md new file mode 100644 index 00000000..2bc72b9b --- /dev/null +++ b/plugins/compound-engineering/skills/compound-foundations/assets/FRONTEND.md @@ -0,0 +1,35 @@ +# FRONTEND + +## Component Conventions + +- Component directory pattern: [PLACEHOLDER] +- Naming pattern: [PLACEHOLDER] +- Styling approach: [PLACEHOLDER] + +## State Management + +- Local state pattern: [PLACEHOLDER] +- Shared/global state pattern: [PLACEHOLDER] +- Server state caching pattern: [PLACEHOLDER] + +## API Integration Patterns + +- Boundary adapters live in: [PLACEHOLDER] +- Error handling pattern: [PLACEHOLDER] +- Loading state pattern: [PLACEHOLDER] + +## Accessibility Baseline + +- Keyboard navigation support required +- Semantic HTML for interactive elements +- Color contrast checks in CI/manual review + +## Performance + +- Bundle analysis command: `[PLACEHOLDER]` +- Core rendering risks and mitigations: [PLACEHOLDER] + +## Testing + +- Unit/component tests: `[PLACEHOLDER command]` +- End-to-end tests: `[PLACEHOLDER command]` diff --git a/plugins/compound-engineering/skills/compound-foundations/assets/QUALITY_SCORE.md b/plugins/compound-engineering/skills/compound-foundations/assets/QUALITY_SCORE.md new file mode 100644 index 00000000..a8b1c6a1 --- /dev/null +++ b/plugins/compound-engineering/skills/compound-foundations/assets/QUALITY_SCORE.md @@ -0,0 +1,13 @@ +# QUALITY SCORE + +Use this file to track module health over time. + +Grades: +- `A`: Strong tests, low incident rate, clear boundaries. +- `B`: Mostly healthy, minor known issues. +- `C`: Noticeable drift, recurring incidents. +- `D`: High risk, immediate cleanup needed. + +| Module | Tests | Last Reviewed | Grade | Known Issues | +|---|---|---|---|---| +| [PLACEHOLDER module] | [PLACEHOLDER test status] | [PLACEHOLDER YYYY-MM-DD] | [PLACEHOLDER A-D] | [PLACEHOLDER summary] | diff --git a/plugins/compound-engineering/skills/compound-foundations/assets/SECURITY.md b/plugins/compound-engineering/skills/compound-foundations/assets/SECURITY.md new file mode 100644 index 00000000..9ed6c7bd --- /dev/null +++ b/plugins/compound-engineering/skills/compound-foundations/assets/SECURITY.md @@ -0,0 +1,37 @@ +# SECURITY + +## Scope + +Document security boundaries and standard patterns. + +## Authentication and Authorization + +- [PLACEHOLDER auth mechanism] +- [PLACEHOLDER authorization boundary checks] + +## Input Validation Boundaries + +- Validate external input at [PLACEHOLDER boundary]. +- Reject unknown fields for [PLACEHOLDER payload types]. + +## Secrets Management + +- Store secrets in [PLACEHOLDER secret manager/env pattern]. +- Never commit secrets to repo. +- Rotate [PLACEHOLDER critical credentials] on schedule. + +## Dependency Auditing + +- Audit command: `[PLACEHOLDER dependency audit command]` +- Remediation SLA: [PLACEHOLDER policy] + +## Logging and PII + +- Do not log [PLACEHOLDER sensitive fields]. +- Redact [PLACEHOLDER token/key patterns]. + +## Incident Response + +- Owner: [PLACEHOLDER] +- Escalation path: [PLACEHOLDER] +- Postmortem storage: [PLACEHOLDER docs path] diff --git a/plugins/compound-engineering/skills/compound-foundations/assets/TECH_DEBT.md b/plugins/compound-engineering/skills/compound-foundations/assets/TECH_DEBT.md new file mode 100644 index 00000000..88be5a70 --- /dev/null +++ b/plugins/compound-engineering/skills/compound-foundations/assets/TECH_DEBT.md @@ -0,0 +1,21 @@ +# TECH DEBT + +Track recurring implementation gaps. + +Promotion rule: +- If an issue appears 3+ times, consider promoting it to `docs/CONVENTIONS.md`. + +Status values: +- `active` +- `scheduled` +- `resolved` + +Severity values: +- `critical` +- `high` +- `medium` +- `low` + +| Issue | Occurrences | Severity | Status | Source | +|---|---:|---|---|---| +| [EXAMPLE issue label] | 1 | medium | active | [EXAMPLE source path] | diff --git a/plugins/compound-engineering/skills/compound-foundations/references/agent-legibility-checklist.md b/plugins/compound-engineering/skills/compound-foundations/references/agent-legibility-checklist.md new file mode 100644 index 00000000..e04699c0 --- /dev/null +++ b/plugins/compound-engineering/skills/compound-foundations/references/agent-legibility-checklist.md @@ -0,0 +1,169 @@ +# Agent Legibility Checklist + +## Overview + +Agent-legible repos are easy to search, easy to navigate, and easy to modify safely. +This checklist focuses on concrete, observable repo characteristics. + +Use it during setup, refactors, and post-incident cleanups. + +## Core Principle + +Design for reliable agent execution, not only human aesthetics. +A neat codebase that is hard to grep is still expensive for agents. + +## Quick Audit + +- [ ] File and directory names are literal and domain-specific. +- [ ] Errors explain what failed and what to do next. +- [ ] Domain docs exist under `docs/` with stable paths. +- [ ] Entry docs link to deeper docs in at most two hops. +- [ ] Conventions are written and easy to find. + +## Technology Choices + +Prefer boring, well-known tools unless there is a strong reason otherwise. + +### Preferred + +- Stable frameworks with large documentation footprints. +- Tools with deterministic CLI behavior. +- Libraries with predictable versioning and changelogs. +- Data formats that are machine-parseable and human-readable. + +### Risky + +- Opaque wrappers around core workflows. +- Frameworks with weak documentation or frequent breaking changes. +- Custom DSLs for common tasks that hide runtime behavior. + +## Code Layout + +### Good patterns + +- One responsibility per module. +- Explicit boundaries between domain, infra, and UI. +- Small helper modules near the caller. +- Consistent naming for service objects and adapters. +- File names matching exported types/classes. + +### Anti-patterns + +- Buckets named `misc`, `utils2`, `helpers_old`. +- Huge files combining parsing, IO, and business rules. +- Hidden side effects in initializers. +- Generic names like `manager` or `processor` with no context. + +## Naming Conventions + +Names should answer "what does this do" without opening the file. + +### Use + +- `invoice_reconciliation_runner.ts` +- `user_session_boundary.rb` +- `email_thread_indexer.py` + +### Avoid + +- `runner.ts` +- `stuff.rb` +- `handler.py` + +## Error Messages That Teach + +Error text should include: + +- What failed. +- What input triggered it. +- One likely fix. + +Example: + +```text +Invalid stage "deploying" in plan frontmatter. +Allowed values: active, completed, archived. +Fix: set `status: active` or `status: completed`. +``` + +## Grepability Standards + +- Keep key terms stable across docs, code, and commands. +- Prefer explicit literals over magic constants. +- Include domain nouns in function names. +- Use consistent table headers in markdown artifacts. + +## Documentation Standards + +- `CLAUDE.md` maps the repo. +- `docs/ARCHITECTURE.md` explains module boundaries. +- `docs/CONVENTIONS.md` defines coding rules. +- `docs/TECH_DEBT.md` tracks recurring issues. +- `docs/QUALITY_SCORE.md` tracks drift and review state. + +## Testing for Legibility + +Create lightweight checks: + +- Lint for ambiguous directory names. +- Check `CLAUDE.md` line count and required sections. +- Validate required markdown tables in debt/quality docs. +- Fail CI when docs are missing after feature templates are generated. + +## Review Checklist + +Run this list when reviewing PRs: + +- [ ] Can a new agent find the right file in under two searches? +- [ ] Are new modules named by domain behavior? +- [ ] Do new errors include remediation hints? +- [ ] Are conventions updated for new patterns? +- [ ] Are new docs cross-linked from existing maps? + +## Promotion Signals + +Promote a rule from guidance to convention if: + +- It appears in 3+ review comments. +- It caused a production issue. +- It is easy to enforce mechanically. + +Promote from convention to enforcement if: + +- Violations keep recurring after documentation. +- The rule has low false positive risk. +- The fix can be auto-suggested in lint output. + +## Example: Before and After + +### Before + +- Failure messages: "invalid input" +- No conventions doc +- Mixed naming style + +### After + +- Failure messages include allowed values and next action +- `docs/CONVENTIONS.md` contains naming and boundary rules +- Linter enforces naming and boundary imports + +## Practical Command Snippets + +```bash +# Check map size +wc -l CLAUDE.md + +# Find ambiguous files +rg -n "utils|misc|helper" app lib src + +# Verify required docs exist +for f in docs/CONVENTIONS.md docs/TECH_DEBT.md docs/ARCHITECTURE.md; do test -f "$f" || echo "missing: $f"; done +``` + +## Success Criteria + +- Search is predictable. +- Docs point to the right depth quickly. +- Repeated mistakes are documented and enforced. +- A new agent can contribute safely in one session. diff --git a/plugins/compound-engineering/skills/compound-foundations/references/architecture-docs.md b/plugins/compound-engineering/skills/compound-foundations/references/architecture-docs.md new file mode 100644 index 00000000..9efcca33 --- /dev/null +++ b/plugins/compound-engineering/skills/compound-foundations/references/architecture-docs.md @@ -0,0 +1,154 @@ +# Architecture Docs + +## Overview + +Architecture docs should answer: + +- Where does behavior live? +- Which boundaries matter? +- What must never happen? + +Keep architecture docs concise and operational. + +## Codemap, Not Atlas + +A codemap highlights navigation and invariants. +It is not a full narrative of every module. + +Good architecture docs help agents find the right place quickly. + +## Recommended Structure + +1. Bird's-eye overview +2. Codemap by module +3. Data flow summary +4. Invariants +5. Cross-cutting concerns + +## Bird's-Eye Overview + +Describe the system in a few paragraphs: + +- Domain purpose +- Core execution paths +- Main integration boundaries + +Avoid implementation trivia here. + +## Codemap Section + +For each module, capture: + +- Path +- Responsibility +- Key types/functions +- Allowed dependencies + +Example entry: + +```markdown +- `src/boundaries/payments/` + - Purpose: Parse and validate external payment events. + - Key types: `PaymentEvent`, `ParsedPayment`. + - Depends on: `src/lib/schema`, `src/domain/payments`. +``` + +## Data Flow Section + +Describe major flows in simple steps. + +Example: + +1. Inbound webhook enters boundary parser. +2. Parsed event becomes domain command. +3. Domain service updates state. +4. Outbound projection updates read model. + +## Invariants Section + +Capture critical "must always" and "must never" rules. + +Examples: + +- Must always parse untrusted input at boundary layer. +- Must never call external APIs from domain entities. +- Must always include source link for new conventions. + +## Absence Invariants + +Document what does not exist by design. +This prevents accidental reintroduction. + +Examples: + +- No business logic in controllers. +- No cross-module imports from UI into domain. +- No schema-less payloads crossing boundaries. + +## Cross-Cutting Concerns + +Cover shared concerns once: + +- Observability +- Security boundaries +- Background jobs +- Caching +- Error handling conventions + +## Drift Signals + +Architecture docs are stale when: + +- Module names changed but codemap did not. +- New boundaries are unlisted. +- Invariants conflict with current code. + +## Update Trigger Rules + +Update architecture docs when: + +- New top-level module appears. +- Dependency direction changes. +- Domain boundary changes. +- New cross-cutting concern is introduced. + +## Anti-Patterns + +- 100-page architecture novels. +- Diagrams with no corresponding code paths. +- Vague terms like "service layer" with no files. +- No invariants section. + +## Review Questions + +- Can a new engineer find the right module in under one minute? +- Are dependency directions explicit? +- Are forbidden patterns documented? +- Are examples tied to real paths? + +## Example Skeleton + +```markdown +# ARCHITECTURE + +## Bird's-Eye +[summary] + +## Codemap +- [module entries] + +## Data Flow +- [flow steps] + +## Invariants +- [must/must-not list] + +## Cross-Cutting Concerns +- [shared concerns] +``` + +## Success Criteria + +- Architecture doc is short, navigable, and actionable. +- Invariants are explicit and testable. +- Engineers and agents can route work correctly on first pass. diff --git a/plugins/compound-engineering/skills/compound-foundations/references/corrections-over-waiting.md b/plugins/compound-engineering/skills/compound-foundations/references/corrections-over-waiting.md new file mode 100644 index 00000000..052e40ef --- /dev/null +++ b/plugins/compound-engineering/skills/compound-foundations/references/corrections-over-waiting.md @@ -0,0 +1,110 @@ +# Corrections Over Waiting + +## Overview + +Throughput matters. +Excessive waiting creates larger batches and harder reviews. +Prefer short loops with fast corrections. + +## Principle + +Ship reversible changes quickly. +Reserve hard gates for irreversible actions. + +## Why It Works + +- Smaller diffs are easier to reason about. +- Bugs are isolated to narrow changes. +- Follow-up fixes are cheaper than delayed merges. + +## What to Gate Hard + +- Production deploy approval. +- Data migrations with irreversible transforms. +- Security-sensitive config changes. + +## What to Keep Fast + +- Documentation updates. +- Convention refinements. +- Non-breaking refactors. +- Incremental enforcement improvements. + +## PR Size Guidance + +- Prefer PRs that can be reviewed in minutes. +- Split backend/frontend shifts into separate units. +- Commit by logical unit, not by file count. + +## Incremental Commit Pattern + +Commit when a unit is complete and testable. +Do not wait for the full initiative to finish. + +Examples: + +- Add new skill scaffolding and references. +- Add setup integration. +- Add compound decision-gate integration. + +## Handling Regressions + +If a quick change regresses behavior: + +1. Reproduce immediately. +2. Add follow-up fix quickly. +3. Capture issue in solution docs if non-trivial. +4. Promote rule if repetition appears. + +## Anti-Patterns + +- Giant "everything" PRs. +- Blocking on subjective polish before merge. +- Delaying harmless fixes until major releases. + +## Decision Checklist + +Before delaying merge, ask: + +- Is the risk irreversible? +- Is the change isolated and testable? +- Can we correct quickly if needed? + +If not irreversible, bias toward shipping and correcting. + +## Operational Rules + +- Keep branch lifetime short. +- Rebase early and often. +- Resolve merge conflicts while context is fresh. +- Prefer additive changes for easier rollback. + +## Relationship to Foundations + +Fast corrections work best when foundations are strong: + +- Conventions reduce review ambiguity. +- Tech debt tracking prevents hidden accumulation. +- Quality score surfaces drift quickly. + +## Communication Pattern + +When shipping incremental units, include: + +- What changed. +- Why now. +- What remains. +- Risk level. + +## Example Flow + +1. Capture solved issue. +2. Promote to convention when repeated. +3. Add lint rule after convention drift. +4. Ship each step separately. + +## Success Criteria + +- Work flows continuously with small, reversible units. +- Teams correct quickly instead of waiting for perfect conditions. +- Foundation quality improves without blocking delivery. diff --git a/plugins/compound-engineering/skills/compound-foundations/references/entropy-management.md b/plugins/compound-engineering/skills/compound-foundations/references/entropy-management.md new file mode 100644 index 00000000..de643121 --- /dev/null +++ b/plugins/compound-engineering/skills/compound-foundations/references/entropy-management.md @@ -0,0 +1,132 @@ +# Entropy Management + +## Overview + +All repos drift. +Without active gardening, drift compounds into friction. +Entropy management keeps the system usable over time. + +## Principle + +Treat maintenance as a continuous, scheduled activity. +Do not wait for cleanup until the repo feels painful. + +## Observable Entropy Signals + +- Repeated fixes for the same issue. +- Growing TODO and FIXME comments. +- Stale docs with broken links. +- Decreasing confidence in conventions. +- Increasing review time for simple changes. + +## Core Artifacts + +- `docs/TECH_DEBT.md` for debt inventory. +- `docs/QUALITY_SCORE.md` for module health. +- `docs/CONVENTIONS.md` for current rules. +- `docs/solutions/` for solved incidents. + +## Debt Tracking Standard + +Use a normalized table with consistent columns: + +`Issue | Occurrences | Severity | Status | Source` + +This allows easy parsing and trend analysis. + +## Debt Lifecycle + +1. Capture issue. +2. Track occurrence count. +3. Prioritize severity. +4. Decide: fix now, schedule, or promote. +5. Promote to convention after 3+ occurrences. + +## Quality Score Pattern + +Assign grades per module (A-D) based on: + +- Test confidence. +- Incident frequency. +- Code clarity. +- Architectural alignment. + +Update grades with date and reviewer. + +## Weekly Gardening Ritual + +- Review new solution docs. +- Increment debt occurrences. +- Regrade modules touched this week. +- Identify one debt item to retire. + +## Monthly Gardening Ritual + +- Archive obsolete debt items. +- Promote recurring debt to conventions. +- Add enforcement for repeat convention violations. + +## Drift Detection Ideas + +- Check for docs changed >90 days ago with active modules. +- Flag conventions with no source links. +- Flag debt entries without status owner. + +## Operational Queries + +```bash +# Find stale docs +find docs -name '*.md' -mtime +90 + +# Count TODO hotspots +rg -n "TODO|FIXME" app lib src + +# Spot repeated problem tags +rg -n "tags:" docs/solutions | sort +``` + +## Anti-Patterns + +- Treating debt as a parking lot with no follow-up. +- Recording debt without source links. +- Grading quality once and never updating. +- Mixing debt and feature roadmap in one doc. + +## Decision Framework + +### Fix immediately when: + +- Customer impact is ongoing. +- Security or data integrity is involved. +- The fix is small and low-risk. + +### Schedule when: + +- Impact is moderate. +- Work needs coordination across teams. +- There is a clear owner and date. + +### Promote when: + +- Pattern repeats 3+ times. +- Root cause is process or convention gap. +- Rule can prevent future repeats. + +## Example Entry + +```markdown +| Missing boundary parser for inbound webhook payloads | 3 | high | active | docs/solutions/integration-issues/webhook-parser-gap-20260213.md | +``` + +## Governance Guidance + +- Keep debt reviews short and regular. +- Make status explicit: active, scheduled, resolved. +- Link every entry to evidence. + +## Success Criteria + +- Debt is visible and actionable. +- Repeated patterns are promoted. +- Quality scores improve in high-change modules. +- Drift is addressed before it becomes crisis work. diff --git a/plugins/compound-engineering/skills/compound-foundations/references/feedback-loop-patterns.md b/plugins/compound-engineering/skills/compound-foundations/references/feedback-loop-patterns.md new file mode 100644 index 00000000..26f0e8c8 --- /dev/null +++ b/plugins/compound-engineering/skills/compound-foundations/references/feedback-loop-patterns.md @@ -0,0 +1,179 @@ +# Feedback Loop Patterns + +## Overview + +Compounding quality depends on promotion loops. +A good loop captures one lesson once, then applies it everywhere. + +## The Promotion Ladder + +Use this escalation path: + +1. Review comment +2. Solution doc +3. Convention entry +4. Mechanical enforcement + +Each step increases reliability and lowers repeated review load. + +## When to Promote + +Promote when any of these are true: + +- Same issue appears 3+ times. +- Fix required senior reviewer intervention. +- Rule can be stated clearly and checked consistently. + +## Promotion Heuristics + +### Promote to convention + +- Rule is stable across modules. +- Violations are frequent but not always machine-detectable. +- Context/rationale matters to engineers. + +### Promote to enforcement + +- Rule is objective. +- Violation detection is deterministic. +- Auto-fix or actionable message is possible. + +## Pattern: Review Comment -> Doc + +Capture the failure as a single issue file in `docs/solutions/`. +Use exact symptoms, root cause, and code-level fix. + +Include: + +- Trigger condition. +- Example failure. +- Working remediation. +- Prevention guidance. + +## Pattern: Doc -> Convention + +Add a concise rule to `docs/CONVENTIONS.md`. +Structure every entry with: + +- Rule. +- Why it exists. +- Source link to the solution doc. + +## Pattern: Convention -> Enforcement + +Codify only after convention drift repeats. + +Possible mechanisms: + +- ESLint custom rule. +- RuboCop cop. +- Static analyzer query. +- CI script validating file structure. + +## Language Examples + +### TypeScript + +Recurring issue: untyped `any` in API boundaries. + +- Convention: "Boundary parsing must return typed DTOs." +- Enforcement: ESLint rule blocking `any` in `src/boundaries/**`. + +### Ruby + +Recurring issue: business logic in controllers. + +- Convention: "Controllers orchestrate, domain logic lives in models/services." +- Enforcement: custom RuboCop cop for controller complexity thresholds. + +### Python + +Recurring issue: ad-hoc dict payloads crossing module boundaries. + +- Convention: "Use dataclasses or typed models at boundaries." +- Enforcement: mypy strict mode for boundary packages. + +### Go + +Recurring issue: ignored errors. + +- Convention: "No ignored `err`; return or wrap with context." +- Enforcement: `errcheck` in CI with package allowlist exceptions. + +## Decision Matrix + +| Signal | Action | +|---|---| +| First occurrence | Keep in review feedback | +| Second occurrence | Add solution documentation | +| Third occurrence | Promote to convention | +| Repeats after convention | Add mechanical enforcement | + +## Quality of a Good Convention Entry + +- Specific scope. +- One clear rule. +- One concise rationale. +- One source link. +- One example if needed. + +Avoid long essays in conventions. +Push detailed narrative into solution docs. + +## Common Anti-Patterns + +- Skipping documentation and jumping straight to lint rules. +- Conventions with no source evidence. +- Enforcement rules with many false positives. +- Stale conventions that no one follows. + +## Maintenance Cadence + +Weekly: + +- Review new solution docs. +- Identify candidates with recurring tags. + +Monthly: + +- Review conventions with low adoption. +- Archive obsolete conventions. + +Quarterly: + +- Evaluate enforcement opportunities. +- Remove noisy lint checks. + +## Suggested Workflow Integration + +In `/workflows:compound`: + +- Always show option to promote to convention. +- Mark it as suggested when 3+ similar findings exist. +- Offer tech debt tracking when issue is known but not yet codified. + +## Example Convention Entry + +```markdown +### Error Handling + +- Rule: Boundary parsers must return typed errors with remediation hints. +- Rationale: Opaque errors caused repeated debugging delays. +- Source: docs/solutions/runtime-errors/boundary-parser-missing-context-20260213.md +``` + +## Example Enforcement Rule Summary + +```text +Rule: no-untyped-boundary-parse +Scope: src/boundaries/** +Message: Parse external input into typed DTOs before crossing domain boundary. +Fix: Use parseIncomingX() helper with schema validation. +``` + +## Success Criteria + +- Repeated findings graduate out of review comments. +- Convention docs stay concise and evidence-backed. +- Enforcement is targeted and low-noise. +- Teams spend less time re-learning the same lesson. diff --git a/plugins/compound-engineering/skills/compound-foundations/references/mechanical-enforcement.md b/plugins/compound-engineering/skills/compound-foundations/references/mechanical-enforcement.md new file mode 100644 index 00000000..7646d878 --- /dev/null +++ b/plugins/compound-engineering/skills/compound-foundations/references/mechanical-enforcement.md @@ -0,0 +1,148 @@ +# Mechanical Enforcement + +## Overview + +Documentation improves understanding. +Enforcement improves consistency. +Use both, in that order. + +## Principle + +If a rule is recurring and objective, enforce it mechanically. +Good enforcement prevents drift without adding review burden. + +## Enforcement Spectrum + +1. Checklist in review template +2. Convention in docs +3. CI check +4. Linter/static rule +5. Build-breaker with remediation hints + +## What to Enforce + +- Boundary import direction. +- Required docs presence. +- Table schema for tech debt and quality score docs. +- Naming conventions for critical modules. +- Error message shape for boundary failures. + +## What Not to Enforce + +- Subjective style preferences. +- Rule sets with high false positives. +- Experimental conventions under active debate. + +## Language Playbooks + +### Ruby + +- `Rakefile` tasks for doc checks. +- RuboCop cops for boundary and naming rules. +- `bin/ci` entry point for deterministic CI. + +Example: + +```ruby +namespace :docs do + task :verify do + abort("missing docs/CONVENTIONS.md") unless File.exist?("docs/CONVENTIONS.md") + end +end +``` + +### TypeScript + +- ESLint custom rules for layer boundaries. +- npm scripts for docs and schema checks. +- tsconfig project references for clear module boundaries. + +Example: + +```json +{ + "scripts": { + "check:foundations": "node scripts/check-foundations.mjs" + } +} +``` + +### Python + +- `pyproject.toml` with ruff + mypy policies. +- pytest structural tests for repo artifacts. +- pre-commit hooks for quick local feedback. + +### Go + +- `make lint`, `make verify-docs` targets. +- `golangci-lint` for static checks. +- unit tests for config and parser invariants. + +## Structural Test Pattern + +Treat repo shape as testable: + +- Core docs exist. +- Required tables contain expected headers. +- Plan files include `status` frontmatter. + +## Error Message Design + +Every rule failure should include: + +- What failed. +- Why it matters. +- How to fix it. + +Bad message: + +`invalid conventions` + +Good message: + +`docs/CONVENTIONS.md missing section "Error Handling". Add the section or run foundation generator.` + +## Adoption Strategy + +1. Start with non-blocking checks. +2. Measure false positives. +3. Tune messages and scope. +4. Promote to blocking once stable. + +## Template: Foundation Check Script + +```bash +#!/usr/bin/env bash +set -euo pipefail + +required=( + "docs/CONVENTIONS.md" + "docs/TECH_DEBT.md" + "docs/ARCHITECTURE.md" +) + +for f in "${required[@]}"; do + test -f "$f" || { echo "missing: $f"; exit 1; } +done + +echo "foundation checks passed" +``` + +## Anti-Patterns + +- Blocking CI on day one with noisy rules. +- Enforcing style that has no impact on reliability. +- Hidden enforcement scripts no one can discover. + +## Maintenance + +- Review enforcement rules monthly. +- Remove stale checks tied to retired architecture. +- Track top failing checks and improve guidance. + +## Success Criteria + +- Recurring issues decline over time. +- Lint output teaches rather than punishes. +- Reviews focus on judgment, not repetitive rule checks. diff --git a/plugins/compound-engineering/skills/compound-foundations/references/plans-as-artifacts.md b/plugins/compound-engineering/skills/compound-foundations/references/plans-as-artifacts.md new file mode 100644 index 00000000..f429809b --- /dev/null +++ b/plugins/compound-engineering/skills/compound-foundations/references/plans-as-artifacts.md @@ -0,0 +1,143 @@ +# Plans as Artifacts + +## Overview + +Plans should be durable files with execution state. +Treat planning output as code-adjacent artifacts. + +## Principle + +A plan is not complete when written. +A plan is complete when it records execution and outcomes. + +## Required Frontmatter + +Use a minimal, stable schema: + +```yaml +--- +title: "feat: ..." +status: active +date: YYYY-MM-DD +--- +``` + +Recommended optional fields: + +- `type` +- `shaping` +- `owner` +- `links` + +## Status Lifecycle + +- `active`: work in progress. +- `completed`: shipped. +- `archived`: historical reference. + +Keep transitions explicit. + +## Execution Tracking + +Use markdown checkboxes for acceptance criteria. +Mark tasks complete as work lands. + +Rules: + +- Do not batch-update at the end. +- Keep plan and implementation synchronized. +- Add notes when scope changes. + +## Decision Log Pattern + +Include short decision entries: + +- Decision taken. +- Why it was taken. +- Tradeoff accepted. +- Date. + +This prevents repeated debates and confusion. + +## Linkage Pattern + +Each plan should link to: + +- Shaping doc or originating spec. +- Affected modules. +- Related solution docs. +- Resulting PR. + +## Plan Granularity + +Good plan tasks are: + +- Observable. +- Testable. +- Single logical unit. + +Avoid "do everything" task entries. + +## Integration with Workflows + +During `/workflows:work`: + +- Read the plan first. +- Track task status in a TODO artifact. +- Update plan checkboxes as units complete. +- Update frontmatter status at ship phase. + +## Anti-Patterns + +- Plans with no acceptance criteria. +- No status field. +- Status never updated after shipping. +- Decisions captured only in chat. + +## Example Task Block + +```markdown +## Acceptance Criteria + +- [ ] Add foundations audit step to setup skill +- [ ] Add promotion options to compound decision gate +- [ ] Add tech debt tracking template and workflow +``` + +## Example Decision Log + +```markdown +## Decision Log + +- 2026-02-13: Keep Option 2 and Option 8 separate. + Reason: Required Reading and Convention serve different goals. +``` + +## Quality Check for Plan Files + +- [ ] Frontmatter present and valid +- [ ] Status reflects reality +- [ ] Checkboxes match shipped work +- [ ] Links to artifacts and source docs included + +## Automation Ideas + +- Script to validate required frontmatter keys. +- Script to flag `status: active` plans older than N days. +- Script to verify no unchecked boxes in completed plans. + +## Command Snippets + +```bash +# Find active plans +rg -n "status: active" plans + +# Find completed plans with unchecked tasks +rg -n "status: completed|\- \[ \]" plans +``` + +## Success Criteria + +- Plans are searchable and current. +- Execution state is visible at a glance. +- Decisions and outcomes are preserved in-repo. diff --git a/plugins/compound-engineering/skills/compound-foundations/references/progressive-disclosure.md b/plugins/compound-engineering/skills/compound-foundations/references/progressive-disclosure.md new file mode 100644 index 00000000..bd509869 --- /dev/null +++ b/plugins/compound-engineering/skills/compound-foundations/references/progressive-disclosure.md @@ -0,0 +1,158 @@ +# Progressive Disclosure + +## Overview + +Progressive disclosure gives agents a clear map first, then detail on demand. +The goal is fast orientation without context overload. + +## Principle + +`CLAUDE.md` is a map, not a manual. +Keep it compact and point to deeper documents. + +## Target Shape + +```text +CLAUDE.md +docs/ + ARCHITECTURE.md + CONVENTIONS.md + TECH_DEBT.md + QUALITY_SCORE.md + design-docs/ + plans/ + solutions/ +``` + +## CLAUDE.md Guidelines + +- Target length: around 100 lines. +- Include mission, structure map, and common commands. +- Link to deeper docs. +- Avoid pasting full policies inline. + +## What to Put in CLAUDE.md + +- Repo purpose and boundaries. +- Directory map with one-line descriptions. +- Where conventions live. +- Where architecture docs live. +- Where active plans live. +- How to run key quality commands. + +## What Not to Put in CLAUDE.md + +- Full style guide text. +- Long architecture narratives. +- Historical changelog content. +- Large troubleshooting catalogs. + +## Two-Hop Navigation Rule + +From `CLAUDE.md`, an agent should reach needed depth in two clicks/opens: + +- Hop 1: map to the correct document. +- Hop 2: document section with actionable guidance. + +## Documentation Layers + +### Layer 1: Orientation + +- `CLAUDE.md` +- `README.md` + +### Layer 2: Operating Rules + +- `docs/CONVENTIONS.md` +- `docs/TECH_DEBT.md` +- `docs/QUALITY_SCORE.md` + +### Layer 3: Deep Technical Context + +- `docs/ARCHITECTURE.md` +- `docs/design-docs/*.md` +- `docs/solutions/**/*.md` + +## File Naming Strategy + +- Single canonical docs in `SCREAMING_CASE.md`. +- Collections in lowercase directories. +- Stable names preferred over thematic renames. + +## Cross-Linking Standard + +Every core doc should link to: + +- One upstream map. +- One downstream deep reference. + +Example: + +- `CLAUDE.md` -> `docs/CONVENTIONS.md` +- `docs/CONVENTIONS.md` -> specific solution docs. + +## Review Prompts for Disclosure Quality + +- Can a new contributor find conventions in <30 seconds? +- Can an agent find architecture boundaries without scanning the full repo? +- Are deep docs discoverable from map docs? + +## Anti-Patterns + +- Giant CLAUDE files with mixed responsibilities. +- Duplicate policy text across many docs. +- Deep docs with no links from the map. +- Hidden conventions only in old PR comments. + +## Migration Strategy + +If current docs are monolithic: + +1. Extract one map doc. +2. Split policy docs by topic. +3. Add links from map to policy docs. +4. Add links from policy docs to examples. + +## Example CLAUDE.md Skeleton + +```markdown +# Project Map + +## What This Repo Does +[summary] + +## Directory Structure +- app/: [purpose] +- docs/: [purpose] + +## Conventions +See docs/CONVENTIONS.md + +## Architecture +See docs/ARCHITECTURE.md + +## Active Plans +See docs/plans/ +``` + +## Quality Signals + +Healthy progressive disclosure has: + +- Short map docs. +- Explicit links. +- Limited duplication. +- Fast onboarding. + +## Operational Check + +```bash +wc -l CLAUDE.md +rg -n "docs/CONVENTIONS.md|docs/ARCHITECTURE.md|docs/TECH_DEBT.md" CLAUDE.md +``` + +## Success Criteria + +- Agents start with clear orientation. +- Deep detail is available only when needed. +- Documentation stays maintainable as the repo grows. diff --git a/plugins/compound-engineering/skills/compound-foundations/references/repo-as-system-of-record.md b/plugins/compound-engineering/skills/compound-foundations/references/repo-as-system-of-record.md new file mode 100644 index 00000000..86e7c734 --- /dev/null +++ b/plugins/compound-engineering/skills/compound-foundations/references/repo-as-system-of-record.md @@ -0,0 +1,142 @@ +# Repo as System of Record + +## Overview + +If knowledge is not in the repo, agents cannot reliably use it. +Conversations and memory are not durable interfaces. + +## Principle + +Store operational, architectural, and product knowledge in versioned files. +Prefer stable paths and explicit links. + +## What Belongs in the Repo + +- Architecture boundaries and data flow. +- Conventions and coding policies. +- Known debt and quality status. +- Incident solutions and prevention notes. +- Active plans and execution status. +- Product specs that influence code behavior. + +## Recommended Doc Topology + +```text +docs/ + ARCHITECTURE.md + CONVENTIONS.md + TECH_DEBT.md + QUALITY_SCORE.md + design-docs/ + plans/ + solutions/ +``` + +## Decision Capture Standard + +For important technical decisions, record: + +- Decision statement. +- Context. +- Alternatives considered. +- Why this path was chosen. +- Consequences/tradeoffs. + +Store in `docs/design-docs/`. + +## Solution Capture Standard + +For resolved incidents, store in `docs/solutions/` with: + +- Frontmatter metadata. +- Symptoms. +- Root cause. +- Working fix. +- Prevention guidance. + +## Plan Capture Standard + +Plan files should include status frontmatter: + +- `status: active` while in progress. +- `status: completed` when shipped. + +This enables simple grep-based filtering. + +## Required Links + +- `CLAUDE.md` -> core docs. +- Conventions -> source solution docs. +- Debt entries -> source solution docs. +- Changelog entries -> major doc artifacts when relevant. + +## Update Discipline + +When behavior changes: + +1. Update code. +2. Update conventions if rule changed. +3. Update architecture map if boundaries changed. +4. Update debt/quality artifacts as needed. + +## Review Checks + +Before merge, ask: + +- Are new operational assumptions documented? +- Are behavior-changing rules reflected in conventions? +- Are new incident patterns captured for future lookup? + +## Anti-Patterns + +- "We'll remember this" with no doc update. +- Architecture only in slide decks. +- Conventions only in reviewer comments. +- Multiple conflicting source-of-truth files. + +## Minimal vs Complete + +Start minimal with core docs. +Expand only as complexity grows. +Do not create empty docs just for checkbox compliance. + +## Traceability Benefits + +A repo system-of-record gives: + +- Repeatable onboarding. +- Faster incident resolution. +- Better agent performance. +- Auditability of technical decisions. + +## Migration Strategy + +If docs are scattered: + +1. Pick canonical paths. +2. Move/merge duplicates. +3. Add redirects or links from old locations. +4. Remove dead docs. + +## Example Canonical Paths + +- `docs/CONVENTIONS.md` +- `docs/TECH_DEBT.md` +- `docs/ARCHITECTURE.md` +- `docs/solutions/` + +## Practical Commands + +```bash +# List core docs and timestamps +ls -lah docs/CONVENTIONS.md docs/TECH_DEBT.md docs/ARCHITECTURE.md + +# Find docs missing source links +rg -n "Source:" docs/CONVENTIONS.md docs/TECH_DEBT.md +``` + +## Success Criteria + +- Key engineering knowledge is versioned and discoverable. +- No critical process depends on tribal memory. +- Agents can resolve common tasks from repo context alone. diff --git a/plugins/compound-engineering/skills/compound-foundations/references/visibility-and-tooling.md b/plugins/compound-engineering/skills/compound-foundations/references/visibility-and-tooling.md new file mode 100644 index 00000000..16db80b4 --- /dev/null +++ b/plugins/compound-engineering/skills/compound-foundations/references/visibility-and-tooling.md @@ -0,0 +1,113 @@ +# Visibility and Tooling + +## Overview + +You cannot steer what you cannot see. +Visibility turns quality from intuition into operations. + +## Principle + +Every important foundation artifact should be observable. +Use lightweight, queryable signals over manual memory. + +## What to Make Visible + +- Foundation artifact presence. +- Quality score trends. +- Tech debt occurrence counts. +- Convention promotion candidates. +- Active plan status. + +## Minimum Visibility Stack + +- Markdown artifacts in `docs/`. +- Deterministic scripts to validate shape. +- CI output with clear pass/fail messages. +- Optional dashboard summary for teams. + +## Status Summary Pattern + +Emit compact status lines such as: + +`foundations: 6/8 present | debt: 14 active | promotion candidates: 3` + +This can be shown in CI logs or local CLI output. + +## Structured Log Pattern + +For automation, emit machine-parseable records: + +```json +{"event":"foundation_check","artifact":"docs/CONVENTIONS.md","status":"present"} +{"event":"tech_debt","issue":"missing boundary parser","occurrences":3} +``` + +## Worktree Isolation + +When running multiple efforts in parallel: + +- Use separate worktrees. +- Keep logs and temporary outputs per worktree. +- Avoid shared mutable state in scripts. + +## Dashboard Metrics + +Useful metrics: + +- Number of active debt items. +- Number of unresolved high-severity debt items. +- Average module grade from QUALITY_SCORE. +- Count of recurring patterns above threshold. + +## Alert Thresholds + +Set simple thresholds: + +- Occurrences >= 3 -> suggest convention promotion. +- High severity debt older than N days -> escalate. +- Missing core artifact -> fail setup audit. + +## Tooling Hooks + +- Pre-merge check: foundation artifact validation. +- Weekly cron: stale docs and debt trend report. +- Monthly report: promotion candidates and enforcement opportunities. + +## Command Examples + +```bash +# Core artifact check +for f in docs/CONVENTIONS.md docs/TECH_DEBT.md docs/ARCHITECTURE.md; do + test -f "$f" || echo "missing:$f" +done + +# Count active debt items (table rows) +rg -n "\| .* \| [0-9]+ \|" docs/TECH_DEBT.md | wc -l +``` + +## Anti-Patterns + +- Relying on ad-hoc verbal status updates. +- Non-deterministic scripts with vague output. +- Dashboards with no link to source docs. + +## Human-Friendly + Machine-Friendly + +Aim for both: + +- Human-friendly markdown for context. +- Machine-friendly tables and consistent headers for parsing. + +## Security and Privacy + +When exposing visibility data: + +- Avoid secrets in logs. +- Avoid customer-sensitive payloads in examples. +- Keep source links internal when needed. + +## Success Criteria + +- Team can assess foundation health in one minute. +- Promotion candidates are surfaced automatically. +- Drift signals are caught before major incidents. diff --git a/plugins/compound-engineering/skills/compound-foundations/workflows/audit-foundations.md b/plugins/compound-engineering/skills/compound-foundations/workflows/audit-foundations.md new file mode 100644 index 00000000..bf52672a --- /dev/null +++ b/plugins/compound-engineering/skills/compound-foundations/workflows/audit-foundations.md @@ -0,0 +1,120 @@ +# Workflow: Audit Foundations + + +Read these references before auditing: +1. `../references/progressive-disclosure.md` +2. `../references/repo-as-system-of-record.md` +3. External skill: `https://github.com/anthropics/claude-plugins-official/blob/main/plugins/claude-md-management/skills/claude-md-improver/SKILL.md` + + + +## Step 1: Identify Project Context + +Detect repo shape and stack signals: + +- `Gemfile`, `config/routes.rb` -> Rails +- `package.json`, `tsconfig.json` -> frontend/TS +- `pyproject.toml` -> Python +- `go.mod` -> Go + +Use this only to decide stack-specific checks. + +## Step 2: Audit Core Tier (Always) + +Check these artifacts: + +- `CLAUDE.md` +- `AGENTS.md` (or `agent.md` if your repo uses that naming) +- `docs/CONVENTIONS.md` +- `docs/TECH_DEBT.md` + +Before evaluating CLAUDE/agent context quality, explicitly load and apply the external `claude-md-improver` skill from: + +`https://github.com/anthropics/claude-plugins-official/blob/main/plugins/claude-md-management/skills/claude-md-improver/SKILL.md` + +Use it to produce a concise quality assessment for the repo's instruction files. + +For `CLAUDE.md` and `AGENTS.md`/`agent.md`, check quality: + +- Is it map-style? +- Is it under ~200 lines? +- Does it link to docs artifacts? +- Are commands/workflows actionable and current? +- Are architecture and non-obvious gotchas clear? + +## Step 3: Audit Recommended Tier + +Check: + +- `docs/ARCHITECTURE.md` +- `docs/QUALITY_SCORE.md` +- `docs/design-docs/` +- `docs/plans/` + +## Step 4: Audit Stack-Specific Tier + +Conditionally check: + +- `docs/FRONTEND.md` if frontend stack is detected +- `docs/DESIGN.md` if UI/design system is detected +- `docs/SECURITY.md` if auth/payments/user data exists + +## Step 5: Produce Scorecard + +Output as markdown table: + +| Artifact | Status | Action | +|---|---|---| +| `CLAUDE.md` | present/missing/weak | concrete next action | + +Include summary line: + +`X/Y foundations present.` + +## Step 6: Ask and Generate Missing Artifacts + +Use AskUserQuestion: + +``` +question: "Foundations audit complete. Generate missing artifacts now?" +header: "Generate" +options: + - label: "Create all missing (Recommended)" + description: "Generate all missing files from templates in one pass." + - label: "Choose files" + description: "Pick specific missing artifacts to generate." + - label: "Skip" + description: "Keep the scorecard only for manual follow-up." +``` + +If "Create all missing": +- Invoke `generate-artifacts.md` +- Pass every missing artifact from the scorecard +- Create files immediately in `docs/` (and `CLAUDE.md` only if missing) + +If "Choose files": +- Invoke `generate-artifacts.md` +- Ask which missing artifacts to generate and create only those + +If "Skip": +- Keep audit output only; no files are generated + +## Step 7: Report Promotion Opportunities + +If debt or solution patterns show repeated issues, suggest: + +- Track as tech debt +- Promote to convention + +Do not auto-modify conventions in audit mode. + + + +- [ ] Core tier audited with clear pass/fail status +- [ ] Recommended tier audited with actionable gaps +- [ ] Stack-specific tier checked based on repo signals +- [ ] Scorecard uses `Artifact | Status | Action` format +- [ ] Summary line includes `X/Y foundations present.` +- [ ] AskUserQuestion is shown after audit with `Create all missing` option +- [ ] Missing artifacts can be generated in one pass + diff --git a/plugins/compound-engineering/skills/compound-foundations/workflows/generate-artifacts.md b/plugins/compound-engineering/skills/compound-foundations/workflows/generate-artifacts.md new file mode 100644 index 00000000..8a726bc9 --- /dev/null +++ b/plugins/compound-engineering/skills/compound-foundations/workflows/generate-artifacts.md @@ -0,0 +1,57 @@ +# Workflow: Generate Artifacts + + +Read these references before generating: +1. `../references/progressive-disclosure.md` +2. `../references/mechanical-enforcement.md` + + + +## Step 1: Identify Missing Artifacts + +Input is a list of missing artifacts from the audit workflow. +Supported outputs: + +- `docs/CONVENTIONS.md` +- `docs/TECH_DEBT.md` +- `docs/QUALITY_SCORE.md` +- `docs/ARCHITECTURE.md` +- `CLAUDE.md` +- `docs/SECURITY.md` +- `docs/FRONTEND.md` +- `docs/DESIGN.md` + +## Step 2: Map Artifacts to Templates + +Map each target to `../assets/*` template. +If target file exists, do not overwrite without explicit confirmation. + +## Step 3: Read Project Context + +Use repo context to fill placeholders: + +- Language and framework +- Key directories +- Naming conventions already in use +- Existing tooling commands + +## Step 4: Generate Populated Content + +Write starter docs with: + +- Generic sections preserved +- Project-specific placeholders filled where clear +- Remaining placeholders explicit as `[PLACEHOLDER]` + +## Step 5: Confirm Outputs + +List created files and any remaining placeholders to fill manually. + + + +- [ ] Only requested artifacts are generated +- [ ] Templates are populated with project context +- [ ] Existing files are not clobbered silently +- [ ] Output paths follow docs convention +- [ ] Generated files are readable and actionable + diff --git a/plugins/compound-engineering/skills/compound-foundations/workflows/promote-to-convention.md b/plugins/compound-engineering/skills/compound-foundations/workflows/promote-to-convention.md new file mode 100644 index 00000000..49ff3341 --- /dev/null +++ b/plugins/compound-engineering/skills/compound-foundations/workflows/promote-to-convention.md @@ -0,0 +1,54 @@ +# Workflow: Promote to Convention + + +Read these references before promoting: +1. `../references/feedback-loop-patterns.md` + + + +## Step 1: Gather Promotion Input + +Collect from the current finding: + +- Candidate rule +- Rationale +- Source link to `docs/solutions/...` +- Optional scope (backend/frontend/testing/etc.) + +## Step 2: Ensure Convention File Exists + +If `docs/CONVENTIONS.md` is missing: + +- Create it from `../assets/CONVENTIONS.md` +- Keep user in flow, do not redirect to setup + +## Step 3: Check for Duplicate Rule + +Search by rule keywords and source link. +If equivalent rule exists, suggest updating existing entry instead of duplicating. + +## Step 4: Append Convention Entry + +Append entry in a suitable section with this shape: + +- Rule: [one sentence] +- Rationale: [one sentence] +- Source: [link to solution doc] + +Prefer concise, enforceable language. + +## Step 5: Confirm and Suggest Next Action + +Confirm file update and suggest next action: + +- If highly repeatable, suggest mechanical enforcement. +- If still emerging, track related debt occurrences. + + + +- [ ] Convention file exists after workflow +- [ ] New entry has rule, rationale, and source +- [ ] Duplicate conventions are avoided +- [ ] Entry is concise and enforceable +- [ ] User receives a clear follow-up suggestion + diff --git a/plugins/compound-engineering/skills/compound-foundations/workflows/track-tech-debt.md b/plugins/compound-engineering/skills/compound-foundations/workflows/track-tech-debt.md new file mode 100644 index 00000000..d64ef591 --- /dev/null +++ b/plugins/compound-engineering/skills/compound-foundations/workflows/track-tech-debt.md @@ -0,0 +1,55 @@ +# Workflow: Track Tech Debt + + +Read these references before tracking: +1. `../references/entropy-management.md` +2. `../references/feedback-loop-patterns.md` + + + +## Step 1: Gather Debt Input + +Capture: + +- Issue label +- Severity (`critical`, `high`, `medium`, `low`) +- Status (`active`, `scheduled`, `resolved`) +- Source link (`docs/solutions/...`) + +## Step 2: Ensure Debt File Exists + +If `docs/TECH_DEBT.md` is missing: + +- Create from `../assets/TECH_DEBT.md` +- Continue workflow in-place + +## Step 3: Parse Existing Table + +Expected headers: + +`Issue | Occurrences | Severity | Status | Source` + +If an issue row already exists, increment `Occurrences`. +Else add a new row with `Occurrences = 1`. + +## Step 4: Apply Promotion Rule + +If `Occurrences >= 3`, emit suggestion: + +`This pattern has appeared N times. Consider promoting to convention.` + +Do not auto-promote. + +## Step 5: Confirm Update + +Report whether row was created or incremented. +Include current occurrence count. + + + +- [ ] Debt file exists after workflow +- [ ] Table format remains parseable +- [ ] Existing entries increment correctly +- [ ] New entries include source links +- [ ] Promotion suggestion appears at 3+ occurrences + diff --git a/plugins/compound-engineering/skills/setup/SKILL.md b/plugins/compound-engineering/skills/setup/SKILL.md index 239739a4..25142cc7 100644 --- a/plugins/compound-engineering/skills/setup/SKILL.md +++ b/plugins/compound-engineering/skills/setup/SKILL.md @@ -166,3 +166,50 @@ Agents: {count} configured Tip: Edit the "Review Context" section to add project-specific instructions. Re-run this setup anytime to reconfigure. ``` + +## Step 6: Foundations Check (optional) + +Use AskUserQuestion: + +``` +question: "Would you like to audit your repo's foundations? Checks CLAUDE.md quality, conventions, tech debt tracking, and more." +header: "Foundations" +options: + - label: "Yes (Recommended)" + description: "Run tiered audit: CLAUDE.md quality, conventions, tech debt, architecture docs." + - label: "Skip" + description: "Finish setup without auditing foundations." +``` + +If "Skip": end setup. +If "Yes": explicitly load the foundations skill, then run its audit workflow: + +1. Load skill: `skill: compound-foundations` +2. Invoke workflow: `workflows/audit-foundations.md` +3. After audit results are shown, use AskUserQuestion: + +``` +question: "Audit complete. Do you want to create all missing foundation files now?" +header: "Generate Files" +options: + - label: "Create all missing (Recommended)" + description: "Generate every missing artifact from compound-foundations templates." + - label: "Choose files" + description: "Select specific missing artifacts to generate." + - label: "Skip" + description: "Keep audit report only, no file generation." +``` + +If "Create all missing": +- Invoke `compound-foundations` workflow `workflows/generate-artifacts.md` +- Pass all missing artifacts from the audit scorecard +- Create files immediately in `docs/` (and `CLAUDE.md` only if missing) + +If "Choose files": +- Invoke `compound-foundations` workflow `workflows/generate-artifacts.md` +- Generate only selected missing artifacts + +If "Skip": +- End setup and keep the scorecard as follow-up guidance + +Do not run foundations checks inline in `setup`; always delegate to the `compound-foundations` skill.