From 06ae605051326df8817536b064a33e0fdde8d330 Mon Sep 17 00:00:00 2001 From: Kjell Tore Guttormsen Date: Thu, 26 Mar 2026 20:25:45 +0100 Subject: [PATCH] fix: pedagogical review - add expected output, CLAUDE.md, fix consistency Address findings from pedagogical review simulating a non-expert user: - Add CLAUDE.md to project root (was referenced but missing) - Fix README score from 12/9/1 to 13/8/1 (match feature-map.md) - Add Expected Output sections to examples 01, 02, 05, 09, 10 - Create pipeline-output/ and briefings/ directories - Add example ordering guidance in README - Add plan requirements for examples 11/13 in prerequisites - Add skill frontmatter explanation in GETTING-STARTED.md - Explain Cowork/Dispatch with links in cowork-integration - Expand .gitignore with node_modules and generated output files - Add model override hints in agent frontmatter comments Co-Authored-By: Claude Opus 4.6 (1M context) --- .claude/agents/researcher.md | 2 +- .claude/agents/reviewer.md | 2 +- .claude/agents/writer.md | 2 +- .gitignore | 10 +++++ CLAUDE.md | 62 ++++++++++++++++----------- GETTING-STARTED.md | 13 ++++-- README.md | 15 +++++-- briefings/.gitkeep | 0 cowork-integration/README.md | 11 ++++- examples/01-agent-runtime/prompt.md | 29 +++++++++++++ examples/02-shell-and-files/prompt.md | 28 ++++++++++++ examples/05-memory-system/prompt.md | 29 +++++++++++++ examples/09-security-hooks/prompt.md | 30 +++++++++++++ examples/10-full-pipeline/prompt.md | 39 +++++++++++++++++ pipeline-output/.gitkeep | 0 15 files changed, 237 insertions(+), 35 deletions(-) create mode 100644 briefings/.gitkeep create mode 100644 pipeline-output/.gitkeep diff --git a/.claude/agents/researcher.md b/.claude/agents/researcher.md index d97d7fa..83c4de2 100644 --- a/.claude/agents/researcher.md +++ b/.claude/agents/researcher.md @@ -2,7 +2,7 @@ name: researcher description: Web research agent that searches, reads, and summarizes information from multiple sources. Use when you need current facts, comparisons, or background context. tools: ["WebSearch", "WebFetch", "Read", "Write", "Glob", "Grep"] -model: sonnet +model: sonnet # Change to "opus" for deeper reasoning, or remove this line to use your default model --- # Researcher Agent diff --git a/.claude/agents/reviewer.md b/.claude/agents/reviewer.md index 85800e7..7f5bea6 100644 --- a/.claude/agents/reviewer.md +++ b/.claude/agents/reviewer.md @@ -2,7 +2,7 @@ name: reviewer description: Quality review agent that checks content for accuracy, clarity, and completeness. Use before publishing or sharing any content. tools: ["Read", "Glob", "Grep", "WebSearch", "WebFetch"] -model: sonnet +model: sonnet # Change to "opus" for more thorough review, or remove to use default --- # Reviewer Agent diff --git a/.claude/agents/writer.md b/.claude/agents/writer.md index 1a30c68..bba0031 100644 --- a/.claude/agents/writer.md +++ b/.claude/agents/writer.md @@ -2,7 +2,7 @@ name: writer description: Content drafting agent that produces clear, structured writing. Use for blog posts, documentation, reports, and summaries. tools: ["Read", "Write", "Edit", "Glob", "Grep"] -model: sonnet +model: sonnet # Change to "opus" for higher quality writing, or remove to use default --- # Writer Agent diff --git a/.gitignore b/.gitignore index e0e724e..7d870ef 100644 --- a/.gitignore +++ b/.gitignore @@ -15,5 +15,15 @@ Thumbs.db .env .env.* +# Node +node_modules/ + # Logs *.log + +# Generated output (created by examples) +research-output.md +changelog-summary.md +hacker-news-top5.md +hn-summary-today.txt +project-scaffold/ diff --git a/CLAUDE.md b/CLAUDE.md index a9c4bd2..781ca39 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,35 +1,49 @@ # Claude Code Complete Agent -This is a working companion repo for the article -"Every OpenClaw Feature, Covered by Claude Code." +## What this project is -## What This Repo Does +A companion repo for the article "Every OpenClaw Feature, Covered by +Claude Code." It contains working configuration, 13 examples, and +documentation that maps OpenClaw's 22 capabilities to Claude Code's +ecosystem. -It demonstrates that Claude Code's ecosystem (tools, MCP servers, -plugins, hooks, agents, skills, and triggers) covers the same -20 capabilities that made OpenClaw the fastest-growing open-source -project in history. +## How to use this -## How to Use It +1. Browse `examples/` and paste any prompt into this session +2. Read `feature-map.md` for the full comparison table +3. Follow `GETTING-STARTED.md` to turn this into your personal setup -1. Open this directory in Claude Code: `claude` -2. Try any example from `examples/` by pasting the prompt -3. Explore agents in `.claude/agents/` and skills in `.claude/skills/` -4. Review security hooks in `hooks/` +## What is configured -## Project Memory +- **Agents** (`.claude/agents/`): researcher, writer, reviewer +- **Skills** (`.claude/skills/`): daily-briefing, web-research, send-slack-message +- **Hooks** (`hooks/`): pre-tool-use blocks dangerous commands, post-tool-use logs all actions +- **Playwright MCP** (`.mcp.json`): disabled by default, enable for browser automation examples +- **Permissions** (`.claude/settings.json`): safe defaults with deny list for destructive patterns -This file is the project's persistent memory. Claude Code reads it -at the start of every session. You can add notes, preferences, and -context here. Unlike OpenClaw's vector-search memory, Claude Code -uses a file hierarchy: +## Project structure -- `CLAUDE.md` (this file) - project-level instructions -- `~/.claude/CLAUDE.md` - global personal instructions -- `.claude/settings.json` - permissions and tool configuration +``` +examples/ 13 numbered examples, each with a prompt.md +security/ Permission modes, Auto Mode, hooks, NemoClaw comparison +memory/ How cross-session memory works +automation/ Cron, launchd, /loop, /schedule +messaging/ Channels (iMessage, Telegram, Discord), Slack, Dispatch +browser/ Playwright MCP setup +cowork-integration/ How Code + Cowork + Dispatch replicate OpenClaw +pipeline-output/ Output from example 10 (full pipeline) +briefings/ Output from daily-briefing skill +``` -## Convention +## Memory -- All examples are self-contained. No dependencies to install. -- Hooks use bash. They work on macOS and Linux. -- MCP config in `.mcp.json` uses Playwright (browser automation). +Session state and notes go in `memory/MEMORY.md`. +This file (CLAUDE.md) is for instructions. MEMORY.md is for state. + +## Rules for this project + +- This is a demo repo. Do not add dependencies or build steps. +- Keep examples self-contained. Each should work independently. +- All output files go in `pipeline-output/` or `briefings/`. +- Do not modify files in `security/` or `hooks/` without reviewing + the security implications. diff --git a/GETTING-STARTED.md b/GETTING-STARTED.md index a9855e9..89c4253 100644 --- a/GETTING-STARTED.md +++ b/GETTING-STARTED.md @@ -14,9 +14,9 @@ Here is exactly what to do. ## Step 1: Make Claude Code know you (30 minutes) -Open `CLAUDE.md` and replace the demo content with your own -context. This is the most important file in the entire setup. -Claude reads it at the start of every session. +Open `CLAUDE.md` in the project root and replace the demo content +with your own context. This is the most important file in the entire +setup. Claude reads it at the start of every session. Write it like a briefing for a capable new colleague on their first day: @@ -133,6 +133,13 @@ always-on, but covers most situations. Skills are what transform Claude Code from "general AI assistant" into "my assistant that knows how I work." +### Important: skill file format + +Every skill file needs YAML frontmatter between `---` markers at the top. +Without this, Claude Code will not recognize it as a skill. The `name` field +is what you type after `/` to run it. The `description` field helps Claude +decide when to suggest it. + ### Example: Weekly status report Create `.claude/skills/weekly-status.md`: diff --git a/README.md b/README.md index d5073c2..6feef04 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ Companion repo for the article OpenClaw has 247K GitHub stars and 22 major capabilities. It is the fastest-growing open-source project in history. This repo shows that Claude Code's ecosystem (Code + Cowork + Dispatch) covers 21 of -those 22, with 12 full matches and 9 different approaches. One gap +those 22, with 13 full matches and 8 different approaches. One gap remains: Canvas/A2UI. This is not a theoretical comparison. Clone this repo, open Claude @@ -23,7 +23,8 @@ Code, and try each example yourself. - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) v2.1.86+ - Node.js 18+ (only needed for Playwright MCP) - A terminal (macOS or Linux) -- For Computer Use: Claude Code Desktop app + macOS +- For Computer Use (example 11): Claude Code Desktop app + macOS + Pro or Max plan +- For Auto Mode (example 13): Team plan or higher (research preview) - For Dispatch: Claude mobile app (iOS/Android) No npm install. No Docker. No build step. @@ -52,6 +53,9 @@ Then try: Paste the prompt from examples/01-agent-runtime/prompt.md ``` +If you see Claude start searching the web and writing a file, it works. +Each example includes an "Expected Output" section so you know what to look for. + ## What is in this repo ### Working configuration @@ -97,12 +101,17 @@ Paste the prompt from examples/01-agent-runtime/prompt.md Each example has a self-contained prompt you can paste directly into Claude Code. +**Recommended path:** Examples 01-09 are independent and work in any order. +Example 10 combines all of them into a single pipeline. Examples 11-13 require +additional setup (Desktop app, specific subscription plans) and are documented +separately. + ## The feature map See [feature-map.md](feature-map.md) for the complete 22-row comparison table with verdicts and version requirements. -**Summary:** 12 full match, 9 different approach, 1 gap. +**Summary:** 13 full match, 8 different approach, 1 gap. ## The broader ecosystem diff --git a/briefings/.gitkeep b/briefings/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/cowork-integration/README.md b/cowork-integration/README.md index 4cfe849..2de73dc 100644 --- a/cowork-integration/README.md +++ b/cowork-integration/README.md @@ -1,10 +1,17 @@ # Cowork Integration: The Full OpenClaw Alternative -Claude Code alone covers 55% of OpenClaw features with a full -match and 41% with a different approach. But Claude Code is just +Claude Code alone covers 59% of OpenClaw features with a full +match and 36% with a different approach. But Claude Code is just one product in Anthropic's ecosystem. Together, Claude Code + Cowork + Dispatch get you closer to 95% of what OpenClaw does. +**What are Cowork and Dispatch?** +- [Claude Cowork](https://claude.ai/cowork) is Anthropic's desktop agent for non-developers. + It can control your screen, connect to apps (Slack, Google, Notion), and run scheduled tasks. +- [Dispatch](https://claude.ai/dispatch) is the mobile app for sending tasks to your desktop + agent from your phone. Think of it as texting your computer. +- Both are part of the Claude Max subscription. + ## The ecosystem ``` diff --git a/examples/01-agent-runtime/prompt.md b/examples/01-agent-runtime/prompt.md index 41165cb..35a4d64 100644 --- a/examples/01-agent-runtime/prompt.md +++ b/examples/01-agent-runtime/prompt.md @@ -39,6 +39,35 @@ confirmation between steps unless it hits something ambiguous. --- +## Expected Output + +After 30-60 seconds, you should see a new file `research-output.md` in the +project root. It will look something like this (content varies by month): + +```markdown +# AI Frameworks Released This Month + +## 1. ExampleFramework +- **Released:** March 12, 2026 +- **GitHub:** https://github.com/example/framework (4,200 stars) +- **What it solves:** Simplifies multi-agent orchestration for Python developers. +- **Verdict:** Worth watching. Growing fast with strong community momentum. + +## 2. ... + +## Verdict +1. ExampleFramework - most practical for production use +2. ... +``` + +**How you know it worked:** +- A file called `research-output.md` exists in the project root +- It contains 3 frameworks with star counts and URLs +- It ends with a ranked Verdict section +- You saw WebSearch and WebFetch tool calls streaming in the terminal + +--- + ## Why This Matters This is the agent loop in action: plan, execute, observe, repeat. The same diff --git a/examples/02-shell-and-files/prompt.md b/examples/02-shell-and-files/prompt.md index c81ccd5..4bbb0c0 100644 --- a/examples/02-shell-and-files/prompt.md +++ b/examples/02-shell-and-files/prompt.md @@ -38,6 +38,34 @@ Claude Code will: --- +## Expected Output + +You should see Claude use 5 tool calls in sequence. The final output +includes a directory tree and file contents: + +``` +project-scaffold/package.json +project-scaffold/README.md +project-scaffold/.gitignore +``` + +And the package.json contents: + +```json +{ + "name": "my-project", + "version": "0.1.0", + "description": "A scaffolded project created by Claude Code" +} +``` + +**How you know it worked:** +- A `project-scaffold/` directory exists with 3 files inside +- You saw Bash (mkdir), Write (x3), Bash (find), and Read tool calls +- No permission prompts appeared for these safe operations (they are pre-approved in settings.json) + +--- + ## Why This Matters Shell execution and file I/O are the foundation of every automation. Claude Code diff --git a/examples/05-memory-system/prompt.md b/examples/05-memory-system/prompt.md index a7cd198..4f81f31 100644 --- a/examples/05-memory-system/prompt.md +++ b/examples/05-memory-system/prompt.md @@ -48,6 +48,35 @@ Claude Code will: --- +## Expected Output + +Claude creates `memory/project-notes.md` and then explains how memory works. +The file will look like: + +```markdown +# March 26, 2026 + +- This is a companion repo comparing OpenClaw and Claude Code capabilities +- It contains 13 examples, agents, skills, hooks, and documentation +- The project maps 22 OpenClaw features to Claude Code equivalents + +Memory system demonstrated successfully. +``` + +Claude will then explain something like: + +> "This file is inside the `memory/` directory, which is referenced in +> CLAUDE.md. Because Claude Code loads CLAUDE.md at every session start, +> and CLAUDE.md mentions the memory directory, files here persist across +> sessions without any extra setup." + +**How you know it worked:** +- `memory/project-notes.md` exists and contains today's date +- The three bullets accurately summarize what CLAUDE.md says +- Claude's explanation mentions the CLAUDE.md hierarchy + +--- + ## Why This Matters OpenClaw uses SQLite-vec for semantic memory search across sessions. Claude Code diff --git a/examples/09-security-hooks/prompt.md b/examples/09-security-hooks/prompt.md index 6392781..46889ea 100644 --- a/examples/09-security-hooks/prompt.md +++ b/examples/09-security-hooks/prompt.md @@ -51,6 +51,36 @@ Each entry has the format: `[timestamp] TOOL: bash | STATUS: blocked | CMD: rm - --- +## Expected Output + +Claude will first explain what it expects the hook to do, then attempt the +command. You should see something like: + +``` +I expect the PreToolUse hook (hooks/pre-tool-use.sh) to intercept this +command because it matches the "rm -rf" pattern in the blocked list... + +[Claude attempts: rm -rf /tmp/test-deletion-target] +[Hook blocks the command] + +The command was blocked by the PreToolUse hook. The hook matched "rm -rf" +in the command string and returned exit code 2 with a block decision. +``` + +The audit log (`hooks/audit.log`) will contain an entry like: + +``` +[2026-03-26T10:15:23] TOOL: bash | STATUS: blocked | CMD: rm -rf /tmp/test-deletion-target +``` + +**How you know it worked:** +- The `rm -rf` command was NOT executed (nothing was deleted) +- Claude reported the hook blocked it +- `hooks/audit.log` exists and has at least one entry +- The entry shows STATUS: blocked + +--- + ## Architecture Difference from OpenClaw OpenClaw sandboxes via Docker: the agent runs inside a container that limits diff --git a/examples/10-full-pipeline/prompt.md b/examples/10-full-pipeline/prompt.md index 1b2e8f3..d64e862 100644 --- a/examples/10-full-pipeline/prompt.md +++ b/examples/10-full-pipeline/prompt.md @@ -62,6 +62,45 @@ typically completes in 2-4 minutes depending on web fetch latency. --- +## Expected Output + +The pipeline takes 2-4 minutes. You will see agent invocations streaming: + +1. **Researcher agent** runs WebSearch and WebFetch (30-60 seconds) +2. **Writer agent** produces a ~400-word draft (15-30 seconds) +3. **Reviewer agent** critiques the draft (15-30 seconds) +4. **Revision** if needed (15-30 seconds) +5. **File writes** to pipeline-output/ and memory/ + +When complete, two new files exist: + +`pipeline-output/permission-modes.md` (the article): +```markdown +# How Claude Code Handles Permission Modes + +Claude Code provides three permission modes that control how much +autonomy the agent has... +[~400 words with accurate technical content] +``` + +`memory/pipeline-log.md` (the execution log): +```markdown +## Pipeline Run - March 26, 2026 + +- **Topic:** How Claude Code handles permission modes +- **Word count:** 412 +- **Issues:** None +- **Duration:** ~3 minutes +``` + +**How you know it worked:** +- Both files exist in the expected directories +- The article is accurate (check against `security/permission-modes-explained.md`) +- The pipeline log has today's date and a word count +- You saw three distinct agent invocations in the terminal + +--- + ## Why This Matters This is what Claude Code looks like as an actual agent platform, not a diff --git a/pipeline-output/.gitkeep b/pipeline-output/.gitkeep new file mode 100644 index 0000000..e69de29