The Self-Improving Agentic OS: How /goal, HTML Artifacts, and Harness Design Compound Your Claude Code Leverage

Three distinct threads today — Kashef's /goal OS playbook, Thariq Shihipar's HTML-as-interface thesis, and RoboNuggets' harness framing — converge on a single insight: the real unit of leverage in Claude Code isn't the prompt, it's the system that generates and refines prompts automatically. If you're still writing ad-hoc commands, you're leaving 80% of the capability on the floor.

Part 1: /goal Is Not a Task Runner — It's a Self-Improvement Protocol

Per Kashef, the dominant misuse pattern is using /goal to execute one-time tasks: migrate this codebase, build this feature, write this snake game. That's using a recursive self-improvement engine as a to-do list checker.

"The real unlock is pointing /goal at your own agentic OS and letting it self-improve overnight."
— Mark Kashef

The mechanic that makes this non-trivial: /goal runs a second model as judge. Your primary agent does the work; a separate model evaluates whether the goal was actually achieved. This is adversarial validation baked into the architecture — the agent can't mark its own homework. This is why /goal produces more durable results than a plain long-running prompt: you get devil's advocate critique at each iteration step, not just at the end.

The Five /goal OS Protocols (Copy-Paste Ready)

Kashef demos five specific operations against ~/.claude. Each maps to a distinct use case:

CLEAN — Audit your skills and rules for contradictions

/goal Audit all skills in ~/.claude/skills/ and rules in ~/.claude/CLAUDE.md.
Identify: (1) duplicate or overlapping skills, (2) rules that contradict each other,
(3) skills with no clear trigger condition. Output a structured report.
Do not modify any files. Success = report with zero ambiguities left unclassified.

Why it works: Over time your ~/.claude accumulates skills from different sessions, often written with different assumptions. Without a clean pass, newer skills silently override older ones with no audit trail. Kashef ran this on 47 skills and 7 rules in under 3 minutes. The second-model judge validates that every item was classified — the agent can't just flag "miscellaneous."

SHARPEN — Iterate a specific skill against a rubric

/goal Take the skill at ~/.claude/skills/[skill-name].md.
Evaluate it against this rubric: (1) trigger condition is unambiguous,
(2) output format is explicitly specified, (3) no circular dependencies on other skills,
(4) includes a failure mode clause. Rewrite the skill until it scores 4/4.
Success = skill file passes all four rubric criteria when re-evaluated by a fresh read.

Why it works: Rubric-driven iteration forces the agent to make the success condition explicit before it starts editing. Without a rubric, "improve this skill" produces cosmetic rewrites. With a rubric, each iteration has a binary pass/fail condition the judge model can score objectively.

REVIVE — Resurrect dormant projects with current context

/goal Scan ~/.claude/projects/ for any project directory not modified in the last 14 days.
For each dormant project: read the last session notes, identify the blocking issue
that caused work to stop, and produce a "re-entry brief" — a single file with:
current state, the specific next action, and estimated steps to completion.
Success = re-entry brief exists for every dormant project, each with a non-empty "next action."

Why it works: Projects stall because the re-entry cost is high — you've lost context. The REVIVE protocol front-loads re-contextualization automatically. Kashef has 22 half-built projects; this is the pattern that keeps them from becoming permanent dead weight.

FORGE — Extract new skills from your own session history

/goal Read the last 10 session transcripts in ~/.claude/sessions/.
Identify any prompt pattern I used more than twice that doesn't have a corresponding
skill file. For each pattern found: draft a new skill file with trigger condition,
input format, output format, and one example. Success = at least one new skill file
created that didn't exist before this run.

Why it works: You're already solving recurring problems repeatedly — you just haven't codified the solution. FORGE mines your own behavior and crystallizes it. The second model judges whether the extracted pattern is genuinely recurrent vs. a one-off. This is your OS learning from you, not just executing for you.

MAINTAIN — Scheduled heartbeat with /loop + /goal

# In a cron job or scheduled runner:
claude --loop "/goal Check ~/.claude for: (1) skills added since last maintenance run,
(2) rules modified since last run, (3) any project re-entry briefs marked 'stale'.
Update a maintenance log at ~/.claude/maintenance.md with timestamp and diff.
Success = maintenance.md updated with no unresolved items."

Why it works: This is the autonomous maintenance layer. /loop keeps the agent running; /goal gives it a success condition to exit on. Together they create a heartbeat that runs while you sleep. Per Kashef, this is one of three ways to run Claude Code autonomously — the other two being direct API calls and scheduled claude -p invocations.

The Three Autonomous Run Modes (Reference Chart)

graph TD A[Need autonomous Claude Code run?] --> B{Needs loop / retry logic?} B -->|Yes| C[/loop + /goal\nHeartbeat maintenance\nSelf-terminates on success] B -->|No| D{Needs scheduled trigger?} D -->|Yes| E[Cron + claude -p\nOne-shot scheduled runs\nNo retry logic] D -->|No| F[Direct API call\nProgrammatic trigger\nFull control over parameters] C --> G[Best for: OS maintenance,\nproject audits, nightly cleanup] E --> H[Best for: Reports,\ndaily digests, backups] F --> I[Best for: CI/CD integration,\nevent-driven workflows]

Part 2: HTML Artifacts Are Your Agent's Communication Protocol, Not Just Pretty Output

Thariq Shihipar (Anthropic Claude Code team) makes a claim that sounds like a UI preference but is actually an architectural argument: HTML is a better medium than Markdown for agent-human communication because it changes your behavior, not just the display.

HTML is the new Markdown: How Anthropic engineers are building with Claude Code | Thariq Shihipar

The mechanism: when you get a Markdown plan, you scan it quickly, nod, and say "looks good." When you get an interactive HTML artifact with visual mockups, toggle-able sections, and clickable states, you actually engage with it. You catch the wrong assumption in section 3. You notice the layout doesn't match what you had in your head. Richer format → longer engagement → better feedback → better implementation. It's a forcing function for upstream quality.

"99% of your AI-generated tokens should go to planning, interfaces, and communication — not production code."
— Thariq Shihipar

This inverts the common workflow where Claude Code goes straight to implementation. Shihipar's ratio: spend the token budget on interactive specs first, then use those specs as implementation artifacts.

The HTML Planning Workflow

flowchart LR A[Raw idea / prompt] --> B[Brainstorm in HTML\nVisual mockup, not text list] B --> C[You engage with artifact\nClick, review, annotate] C --> D[Micro-UI edits\nThrowaway editor for specific sections] D --> E[Plan becomes implementation artifact\nPassed directly to Claude Code] E --> F[Production code] F --> G[Living design system\nin-repo HTML reference]

Concrete Prompt Patterns

Brainstorm-to-HTML (replaces the "give me a plan" prompt):

Generate an interactive HTML artifact that shows three different approaches
to [feature/problem]. Each approach should have: a visual mockup,
a pros/cons section, and an estimated complexity rating.
Make each approach togglable so I can compare them side by side.

Why this beats a bullet list: The toggle mechanic forces you to actually compare options rather than accepting the first one. The visual mockup reveals assumptions the text description would hide.

Throwaway micro-UI for plan editing:

The implementation plan is in plan.html. Build a minimal HTML editor UI
that lets me directly edit the [specific section] — just that section,
with a save button that writes back to plan.html.
Discard the editor after I'm done. This is throwaway code.

Why throwaway UI is legitimate: Shihipar's framing is "just-in-time documentation." Build the interface for the specific editing task, use it, discard it. The artifact that matters is the plan, not the editor. Stop over-engineering scaffolding.

Living design system prompt:

Create a design-system.html file in the repo root that documents:
all current color tokens, typography scale, spacing system, and component states.
Pull these values from the actual codebase — don't invent them.
This file should be updated automatically whenever I run /maintain.
Format it as a visual reference, not a text spec.

Why in-repo HTML beats a Figma file: The design system travels with the codebase. Every new Claude Code session can reference it. No external dependency, no sync lag, no "which version is current" problem.

The "Complexity Must Earn Its Keep" Rule

Shihipar's prompting philosophy: give Claude constraints, not instructions. The distinction:

| Instructions (worse) | Constraints (better) | |---|---| | "Use a two-column layout" | "The layout must work on mobile — your call on structure" | | "Make the button blue" | "Use the design system tokens for primary actions" | | "Add a loading spinner here" | "The user must have feedback within 200ms of any action" |

Instructions collapse the solution space prematurely. Constraints preserve Claude's judgment while ensuring you get what you actually need. This maps directly to /goal design: you define the success condition (constraint), not the method (instruction).

Part 3: The Harness Frame — What Claude Code Is, and Why It Matters for Your OS Design

RoboNuggets' framing is the most useful conceptual lens today: Claude Code is a harness. The model is the engine; the harness is the system prompts, tooling, and skill infrastructure that wraps it.

Per RoboNuggets:

"The harness is basically the set of system prompts and other tooling in code that wrap this model in order to give it custom instructions or custom skills."

This reframes everything Kashef describes. Your ~/.claude folder isn't "settings" — it's your harness. Every skill file is a tool in that harness. Every rule in CLAUDE.md is a system prompt constraint. When you run FORGE to extract new skills from session history, you're evolving your harness based on empirical usage data.

The competitive insight from the harness frame: the model is commoditized; the harness is the moat. RoboNuggets notes that harness providers can swap out underlying models (Claude Opus, GPT, Gemini) while preserving the skill layer. Your ~/.claude OS, if well-built, is model-agnostic. The skills transfer; the harness survives model updates.

Harness Quality Checklist

This is what separates a high-quality harness from a pile of files:

[ ] Every skill has an unambiguous trigger condition — the agent knows when to use it without guessing
[ ] Rules don't contradict each other — run CLEAN regularly
[ ] Skills have explicit output format specs — not "a good summary" but "a bulleted list with max 5 items, each under 80 chars"
[ ] Failure mode clauses exist — what should the skill do when input is malformed or the task is ambiguous?
[ ] Design system reference exists in-repo — Shihipar's HTML artifact lives at ./design-system.html
[ ] Maintenance log tracks harness state — MAINTAIN writes to ~/.claude/maintenance.md
[ ] Session transcripts are archived — FORGE needs raw material to mine

Part 4: Where the Advisors Converge and Where They Diverge

Strong Consensus: Invest Token Budget Upstream, Not in Production Code

Both Kashef and Shihipar independently arrive at the same ratio: most of your AI effort should go into planning, specification, and system improvement — not direct code generation. Kashef does this by pointing /goal at the OS itself. Shihipar does it by insisting on interactive HTML plans before implementation. Same principle, different execution surfaces.

Partial Tension: Explicit Structure vs. Flexible Constraints

Kashef's approach is maximally explicit — rubrics, checklists, success conditions defined down to the integer. Shihipar argues for constraints over instructions, giving Claude more latitude within boundaries.

These aren't contradictory, but they apply at different layers:

For OS management (Kashef layer): Maximum explicitness wins. You want deterministic behavior from maintenance runs.
For creative/implementation work (Shihipar layer): Constraints over instructions wins. You want Claude's judgment applied to UX and architecture decisions.

The decision rule: the more repeatable the task, the more explicit the success criteria should be. The more creative the task, the more you define the constraint boundary and let Claude solve within it.

graph LR A[Task type?] --> B{Repeatable / mechanical?} B -->|Yes| C[Kashef mode:\nExplicit rubric\nBinary success criteria\nJudge model validates] B -->|No| D{Creative / architectural?} D -->|Yes| E[Shihipar mode:\nDefine constraints\nNot instructions\nHTML artifact for review] D -->|Neither| F[Hybrid:\nConstrain the output format\nLeave method open\nReview via HTML artifact]

RoboNuggets as Meta-Frame

The harness framing from RoboNuggets doesn't conflict with either — it explains why both techniques work. Kashef's CLEAN/SHARPEN/FORGE protocols maintain harness quality. Shihipar's HTML artifacts create better harness inputs (specs that actually communicate intent). Both are harness engineering; they're just operating at different points in the workflow.

Part 5: The Multi-Agent Pipeline vs. MCP Question

From the Lenny community discussion (flagged this week): practitioners are actively debating whether to build multi-agent pipelines or use MCP (Model Context Protocol) for orchestration.

The practical distinction matters for your workflows:

Multi-agent pipeline: You spawn discrete agents with isolated contexts, each with a specific task. They pass artifacts to each other. No shared state. Harder to set up, more robust to context contamination.

MCP: You extend a single Claude Code session with tools that reach out to external services. Same context window, more tools. Simpler to set up, but context bloat is a real failure mode on long tasks.

The decision tree:

flowchart TD A[Need external capability?] --> B{Task requires shared context\nacross capability calls?} B -->|Yes| C[MCP\nSingle agent + tools\nContext stays coherent] B -->|No| D{Risk of context bloat\non long task?} D -->|Yes| E[Multi-agent pipeline\nIsolated contexts\nArtifact handoffs] D -->|No| F{Real-time bidirectionality\nneeded?} F -->|Yes| C F -->|No| E C --> G[Gotcha: Watch context window\nsize on MCP-heavy sessions] E --> H[Gotcha: Artifact format contract\nbetween agents must be explicit]

The failure mode for MCP-heavy sessions: you hit context limits mid-task and the agent's behavior degrades without obvious error signals. The failure mode for multi-agent pipelines: agents disagree on artifact format and the handoff silently corrupts data. Both require explicit contracts — Shihipar's HTML artifact format is one solution on the MCP side; Kashef's skill files with explicit output specs solve it on the pipeline side.

Implementation Protocol: Your Monday Morning Checklist

If you implement nothing else from today, do these in order:

Step 1: Run CLEAN on your current ~/.claude

/goal Audit all files in ~/.claude. List: (1) every skill file with its trigger condition,
(2) every rule in CLAUDE.md, (3) any contradictions between rules,
(4) any skill without a stated output format. Do not modify anything.
Output a markdown table. Success = table has zero blank cells.

Step 2: Convert your most-used plan format to HTML

Take the last spec or plan you wrote in Markdown. Prompt:

Convert this plan to an interactive HTML artifact. Add: (1) a toggle for each major section,
(2) a visual indicator of task status (not started / in progress / done),
(3) an inline comment field I can type into. Make it self-contained — one .html file.

Open it in a browser. Notice what you actually read vs. what you skimmed in Markdown.

Step 3: Schedule your first MAINTAIN run

Pick a time tonight when you won't be working. Set up a cron or a reminder to run:

claude -p "/goal Check ~/.claude/skills/ for any file not referenced in a session 
in the last 7 days. Flag it as 'dormant' in a maintenance log. 
Success = maintenance.md updated with timestamp."

That's it. Three steps. You'll have a cleaner harness, a better planning format, and your first autonomous maintenance run by tomorrow morning.

Today's One Action

Run the FORGE protocol tonight against your last 10 Claude Code sessions. The command:

/goal Read session transcripts in ~/.claude/sessions/ (last 10).
Identify the single prompt pattern I used most frequently that has no corresponding skill file.
Draft that skill file with: trigger condition, input format, output format, one example, one failure mode clause.
Save it to ~/.claude/skills/[descriptive-name].md.
Success = one new skill file exists that codifies a real pattern from my actual usage.

Why this one: every other technique here (CLEAN, SHARPEN, HTML artifacts, MCP vs. pipeline decisions) requires some setup or new habit. FORGE requires nothing except that you've been using Claude Code — which you have. It mines your existing behavior and turns it into permanent leverage. The second model validates the pattern is genuinely recurrent, not a one-off. You wake up tomorrow with a smarter harness than you had yesterday, built entirely from evidence.